- crash-before-rename test: a COMPLETE valid migrated temp beside the
untouched original is discarded and the boot re-migrates — the
sharpest point on the crash timeline, deterministic, no fault
injection needed
- story: all six tasks done with commit hashes, all eight criteria met
with the test that proves each, plus the three deviations from the
plan and why (transcode over replay, lazy head, poison forces
transcode)
- CODE-LOGIC: migration section; also corrected limitation 3, which
still claimed unbounded hot-row chains — iteration 11 closed that
- status board row 12; deploy guide's rollback section gets its real
answer (rolling back across a migration is a migration backwards:
expect the refusal, restore the .bak)
- test_wal 5966 pass, 0 fail
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit 4bb6ece2531e2123eb958c91d9bef4a6528eab3b)
- new docs/guides/deploying-site.md: build, content refresh, systemd
unit, post-deploy verification, rollback, and the gaps behind each
workaround
- leads with the trap that costs the most: shipping a binary does NOT
update chapters. seed_if_empty only fills an EMPTY table and
AdminEdit answers not_found for an unknown slug, so a host with an
existing WO_DATA shows the old chapter list with no error anywhere
- that claim is measured, not argued: a 9-chapter build seeded a data
dir, then the 10-chapter binary against it still 404'd /ch/storage
and rendered 9 nav entries; wiping WO_DATA gave 200 and 10
- records two more blockers found while writing it: both site deps
(porch, writeonce-view) 404 on GitHub and wo.lock is untracked, so
the site submodule cannot build standalone; and the embedded wovm
sets the glibc floor (this machine: 2.38, above Ubuntu 22.04's 2.35)
- build recipe run verbatim before publishing; releasing.md points here
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit 930a715c4a3d847529e3e341edc71c65a7e11d1c)
- extracted to github.com/shoneyJ/writeonce-site with `git subtree
split`, so the site keeps its own 9 commits of history rather than
landing there as a flattened snapshot
- .gitmodules gains the third entry, alongside reference/writeonce-app
and reference/writeonce-api; path is unchanged, so every doc and
script that names docs/examples/site still resolves
- site-accept.sh fails early and says `git submodule update --init`
when the directory is empty. Without it a clone lacking submodules
copies an empty app and fails later as a build error naming nothing
- releasing.md: the steps that edit install/view.wo now say that edit
is a commit in the site repo plus a pointer bump here — editing and
committing only in this repo would record nothing
- gate re-run against the submodule: site-accept 23 checks, 0 failures
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit 4b5634801d5379890bad24c8129cfb23ab6b98df)
- explains replay, the row chain, how a checkpoint flattens it, and why
replay of a long chain is quadratic
- worked SKU example with the actual record layout and back-pointers,
and a trace of the fold showing first-seen-wins
- states plainly why the checkpoint does not bound the hot-row case:
both triggers are ratios over the whole log and nothing counts
per-row chain length
- records the bounded-memory vs linear-time conflict behind the O(N^2)
replay rather than presenting it as an oversight
- closes with the reviewing lesson, since this shape survived several
rounds: complexity bugs hide in the caller's loop, not in the linear
helper being read
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit e6434403d566b5d72a24e9c0dcad1f25a2c16320)
Task 1 of docs/superpowers/plans/2026-08-26-table-residency.md.
- ast.ml: `table_cfg` gains `durable : bool` (default true) and
`resident : residency` (ResAll | ResKeys, default ResAll) — both defaulting
to the pre-existing behaviour, which is what lets every @table written
before this compile byte-identically
- parser.ml: `durable:` takes the existing KwTrue/KwFalse tokens; `resident:`
takes the bare identifiers `all`/`keys`. Given-twice tracked by local seen
flags rather than option fields, so "absent" and "explicitly the default"
stay distinguishable without the AST carrying an option nobody reads
- five new WO-E102 causes, all catalogued in the same commit: durable twice,
resident twice, an unknown resident value, `resident: index` (the
pre-review spelling, with a message naming its replacement), and a retired
design word (mode/store/ram/cold/tiered/paged/mmap/buffer) which gets a
message stating the two real keys instead of a generic "unknown argument"
- dump.ml prints each property ONLY when it differs from its default.
Printing unconditionally would have moved every pre-existing golden, which
this iteration is not allowed to do
- new golden compiler/test/golden/ast/table-residency.wo covers all four
shapes, including a table declaring `resident: all` explicitly and
correctly dumping nothing for it
- verified, not assumed: `git diff --stat` over compiler/test/golden/ is
EMPTY after a WOC_BLESS run, so all 30 pre-existing goldens are untouched.
woc-test 557/0 (was 556), oop-e2e 116/0, employee 8/0; employee, db-bench,
db-actor and porch all still typecheck
- docs: language-surface's @table row now matches what the parser accepts
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- driving case: a 120 GB order table on a 32 GB host. Not a tuning problem;
no eviction policy fixes it. Developer accepted reconsidering the principle
- principle 7 rewritten: durability half UNCHANGED and unconditional
(WAL-logged, fsync before ack, CRC-dropped torn tail); residency half
demoted from law to per-table declaration. Old wording quoted in place so
the amendment is legible, with the reason: a doctrine a real workload
cannot satisfy gets ignored, and the failure it produced was an OOM kill
- spec: docs/superpowers/specs/2026-08-26-table-residency-design.md
One log-structured engine — the WAL already holds every row, so keep an
in-RAM id->offset map and pread rows back. No second engine, no user-space
row cache (the kernel page cache is the hot copy, which is already this
repo's stated position and why it avoids O_DIRECT)
- arithmetic that makes it work: 240M rows x 16 B of index = ~3.8 GB
resident in 32 GB. Indexes stay resident, rows do not. Buys ~2 orders of
magnitude, not infinity — stated plainly in the spec
- grammar: two optional keys, `durable: true|false` and `resident: all|index`,
both defaulting to today's behaviour, so all 28 existing @table
declarations compile untouched and no golden is reblessed
- rejected, with reasons recorded: mmap (rows are pointer-bearing —
table.c returns (uintptr_t)t as the slot word), buffer pool (the Rust-era
phase-12 design that died with that track), paged B-tree (stays rejected),
a three-valued enum, automatic spill, disk-backed-by-default
- self-review caught the budget defaulting to "none" while promising the ERP
developer a diagnostic instead of the OOM killer — contradiction fixed:
the budget defaults to a fraction of host memory, and its value comes from
databasev2 1's swap-onset measurement
- live docs that contradicted the amendment updated (subagent doctrine,
its guide, discarded.md's two rows, iteration 04's read claim, 07, 38);
dated specs/plans left as records. linkcheck 0 broken / 0 anchors
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- README: shipped concurrency/HTTP/WebSockets sat in the roadmap as "not yet
available"; "no package manager" contradicted [deps]; the deps example
would not have compiled (the key IS the module name)
- runtime/README: leads with wovm, wo-rt.c demoted to a historical section;
dropped 2 nonexistent recipes, crates/rt, @gc refcounting, 13 suites -> 18
- employee + log-watcher READMEs claimed "does not compile"; both are gates
- error catalog: +10 emitted codes incl WO-E250, the only diagnostic the
shipped query surface raises; recorded why the sweep rotted
- language-surface: group-by parses, then the typechecker refuses it
- 00-code-review + 00-link-audit re-run; history kept, not rewritten
- 48 dead Rust-era exploration links de-linked rather than re-pointed (their
prose names the retired plan by number); successor map -> discarded.md
- 08-project-structure: compiler/plan/ never existed; corpus has 9 dirs, 5 empty
- releasing.md: dropped a --draft step the workflow never had
- new docs/00-doc-audit.md: findings + disposition, incl one row where the
audit was wrong and the doc it accused was right
- status folders removed: 34 stories flat, status only in frontmatter; 252
links recomputed from resolved paths; board/board-views/structure retaught
- story 24 -> in-progress, since frontmatter is now the only truth
- new iteration 38: fs mutation verbs + net.connect, the two capability
families no iteration owned
- new iteration 39: gofiber/fiber v3.5.0 parity study. The ledger called
CSRF/sessions unblocked by iteration 34's HMAC, but the runtime has no
source of randomness at all
- linkcheck skips .dev/.superpowers: 0 broken paths, 0 bad anchors
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- manual runs skip the tag guard (there is no tag on a dispatch, so
GITHUB_REF_NAME is the branch and the guard always failed) and skip
publishing
- a dispatch now builds, verifies the digest, smoke-tests the
extracted toolchain and reports the glibc floor, then stops
- replaces the throwaway-tag rehearsal in the checklist: no tag to
delete, no draft release to clean up
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- public repos: standard runners free, unlimited minutes; only larger
(4-core+) runners bill there and this workflow does not use one
- private: included minutes per plan, then per-minute; Linux x1 vs
Windows x2 / macOS x10; each job rounds up to the next minute
- sized from a measurement: cold mkdist.sh is 3.4s on 20 cores, so
under a minute on a 2-core runner — setup-ocaml dominates, ~3-10
min per release, and it only runs on a tag
- release assets do not count against Actions artifact storage
- flags that rates drift; check the billing page
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- self-hosted works technically: outbound HTTPS only, no inbound
ports, honours HTTPS_PROXY/NO_PROXY — a box behind a proxy is fine
- but it defeats the pinned-runner decision: the build host sets the
glibc floor, so a workstation runner (2.39 here) puts it back to
2.38+ and drops Ubuntu 22.04 / Debian 12 / RHEL 9
- and a workstation-built release is unattested
- records what self-hosting accepts: jobs run as the starting user,
with that user's ~/.ssh, credentials and network reach — including
hosts named in ~/.ssh/config; worst on public repos, where a
stranger's PR runs code on the runner
- if unavoidable: dedicated VM, unprivileged user, --ephemeral,
segmented network, treat .credentials as a secret
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- states plainly what does NOT trigger it: builds run on a
GitHub-hosted runner, not locally, and only on a `v*` tag push —
pushing master releases nothing
- 14 numbered steps: get the workflow onto GitHub, enable Actions,
allow ocaml/setup-ocaml, the 403/workflow-permissions fallback,
a --draft rehearsal on a throwaway tag, cleanup, then the real tag
- calls out that the rehearsal tag is EXPECTED to fail the tag/VERSION
guard, and how to rehearse the full job instead
- step 8/9: read the runner's glibc floor and reconcile
install/view.wo with it — the runner, not the dev machine, decides
who can run the release
- lists the three likely first-run failures
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- .github/workflows/release.yml: builds, verifies and publishes on a
`v*` tag. `permissions: contents: write` on the injected
GITHUB_TOKEN replaces `gh auth login`; no PAT, nothing to rotate
- runs-on ubuntu-22.04 DELIBERATELY: the build host's glibc caps which
symbol versions the binaries import, and that cap is the floor every
user needs. 22.04 (2.35) includes Ubuntu 22.04 / Debian 12 / RHEL 9;
24.04 (2.39) would exclude them
- guards that fail instead of publishing: tag vs VERSION, produced
asset name vs the filename /install links, sha256, and a smoke test
that builds a hello project with the binaries INSIDE the tarball
- reports the shipped glibc floor so the claim on /install is checkable
from a build log
- releasing.md: pipeline route up front, manual route kept; GH_TOKEN
recipe for non-GitHub CI
Not run — this repo has no CI history and Actions cannot execute
locally. Every guard's shell was dry-run here against the real dist.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- gh's credential is separate from git's: SSH keys let you push but
not call the API, so a machine that pushes can still fail to release
- the five interactive prompts and what to answer, with SSH as the
protocol to match this repo's existing remote
- headless path: PAT scopes (classic repo/read:org/gist, fine-grained
Contents: read and write), --with-token from a 600 file, GH_TOKEN
for automation
- verify with `gh repo view shoneyJ/writeonce` — proves the token
reaches THIS repo, not just that it is valid
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- docs/guides/releasing.md: the steps from `just dist` to a working
download button
- pins the constraint that matters: the asset filename and tag must
match the URL /install links, or the button 404s
- includes verifying the tarball with the binaries INSIDE it, tagging
the built commit, `gh release create` with both files, the web-UI
path, and a curl check of the exact link the site uses
- notes dist/ is gitignored, the shoneyJ/shoneyj path-case difference,
and what a version bump must touch in install/view.wo
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- lexer: backtick raw text literal — content verbatim, no escape
processing, common source margin removed at lex time; `${ }` raw and
`{{ }}` auto-escaping holes
- `{{ e }}` desugars to `esc(${e})` in parser.ml — a Call on the `esc`
in scope, so types/owner/emit/.wob/VM are untouched
- WO-E004 unterminated raw literal; WO-E005 newline inside "..." —
closes a hole where a missing quote silently ate the rest of the file
- wo-html: `Component` interface, `render_all`, `Layout`, README
- framework: `ok_html` joins ok_text/ok_json in http/types.wo
- site + shop restructured to one-feature-one-module MVC (view +
controller per directory, model at the root, bootstrap-only main)
- removed the filler `pad: Int` convention — verified unnecessary for
plain classes, interface dispatch, containers and actors
- corrected recorded claims: gap #1 blocks neither the build nor the
layout; a class crosses module lines, only a free fn is scoped
- docs/guides/language-surface.md — the full grammar inventory
- story 37 landed and moved to done/
Gates: oop-accept MET, oop-e2e 116/0, woc-test 556/0, site 11/0,
web-app 46/0, fibers 10/0, db-actor 8/0
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- constraints-and-grammar: gram.y PK/FK productions, pg_constraint,
RI trigger semantics; writeonce direction — @key as unique alias
(id stays THE key), ref actions (@on_delete), backlink-implies-index
(improves on postgres' not-auto-created FK index)
- indexing-and-point-lookup: AM roster + algorithms (Lehman-Yao,
linear hashing), TID = row address; writeonce gap — probe walks
slabs while idx_bucket exists; O(1) slice direction, non-goals
- card index updated; Rust-era plan-10/11/12 links unlinked (rot)
- docs/guides/database-developer-subagent.md: format, paste-ready
agent definition (doctrine/file map/gates), verification, division
of labor
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
