# 08 — Project structure: the writeonce monorepo

Canonical map of the repository: what every root directory is, who writes to it, and where it is headed as the OOP + systems tracks land. Companion to [`CLAUDE.md`](../CLAUDE.md) (working rules) and the two track specs ([`superpowers/specs/2026-08-01-oop-compiler-vm-design.md`](superpowers/specs/2026-08-01-oop-compiler-vm-design.md), [`superpowers/specs/2026-08-01-systems-track-design.md`](superpowers/specs/2026-08-01-systems-track-design.md)). Plan documents govern the *target* entries; this doc is the one place the whole shape is visible.

## The one-page map

```
writeonce-all/
├── compiler/            ⏳ OCaml `woc` — lexer→parser→types→owner→emit (plans 2, 8)
├── runtime/             ✅ C runtime — wo-rt.c event-loop reference + ⏳ src/ wovm VM (plans 1, 4–7, 9)
├── crates/              ✅ Rust runtime `rt` + 14 phase-scaffold crates — active until C-stack parity
├── tests/               ⏳ corpus/ — conformance fixtures: run / compile-fail / trap / gc / sys / actor / db
├── client/              ⏳ wo-live.js — the ~20 KB live-patch browser runtime (plan 7)
├── scripts/             ⏳ oop-e2e.sh, oop-parity.sh — corpus + parity harnesses (plan 3)
├── prototypes/          ✅ wo-db C++ query-engine reference; ⚠ wo-rt-c = stale duplicate of runtime/
├── .dev/reference/           ✅ v1 crates workspace, colibri, llama-cpp; linux/ + go/ symlinks (per-dev)
├── docs/                ✅ ALL documentation: numbered design docs, plan/, runtime/, examples/, superpowers/
├── content/ data/ wo-data/ static/ templates/ infra/   ✅ v1 blog operating assets (migration-plan governed)
├── justfile             recipes: rt-c-demo/bench today; woc-/wovm-/oop-accept as plans land
├── Cargo.toml           the Rust workspace root (crates/*; .dev/reference/crates excluded)
└── .dev/                gitignored per-developer links + commit.md draft (see .dev/README.md)
```

✅ exists today · ⏳ created by a named plan · ⚠ cleanup note (below).

## Root directories in detail

### `compiler/` — the OCaml `woc` compiler (target)

Created by plan 2 (`docs/plan/compiler/2026-08-01-woc-compiler-front.md`), grown by plans 3 and 8.

```
compiler/
├── dune-project
├── README.md            orientation: pipeline map, build/test commands
├── plan/                compiler-track docs: architecture.md + plans 2, 3, 8
│                        (recorded exception to the docs-under-docs/ rule)
├── src/                 one module per stage: diag, token, lexer, ast, parser,
│                        types, owner, emit, disasm, dump
├── bin/main.ml          the woc executable (check/emit/build modes)
└── test/                golden runner + golden/ fixtures per stage
```

Doctrine: OCaml stdlib only — no Menhir, no ppx, no opam libraries; handwritten lexer and recursive-descent parser. Architecture map with the marked reference-study paths: [`docs/plan/compiler/architecture.md`](plan/compiler/architecture.md).

### `runtime/` — the C runtime (canonical, partially landed)

The root-level home of the C track. Today it holds the shipped thread-per-core io_uring reference (`wo-rt.c`, phases A–F done — see [`plan/exploration/c-runtime/00-plan.md`](plan/exploration/c-runtime/00-plan.md)) plus its `bench/` and Makefile. The VM and every runtime module land beside it under `src/`:

```
runtime/
├── Makefile             wo-rt today; wovm + test targets as plan 1 lands
├── README.md            orientation only (docs rule: real docs live under docs/)
├── wo-rt.c              UNTOUCHED phase A–F event-loop reference
├── bench/               HTTP bench + goref/ Go comparison server
├── src/                 ⏳ wob.h, obj, borrow, cont, gc, loader, vm, builtin, main   (plan 1)
│                        ⏳ sched, mailbox, shard                                     (plan 4)
│                        ⏳ table, wal, db                                            (plan 5)
│                        ⏳ http, json, router, handlers                              (plan 6)
│                        ⏳ ws, sub, htmlx, assets                                    (plan 7)
│                        ⏳ sys_env, sys_fs, sys_proc, sys_net, sys_time              (plan 9)
└── test/                ⏳ t.h harness, wob_build assembler, test_*.c, cli_smoke.sh
```

Doctrine: C11, libc only, direct syscalls; computed-goto dispatch with `-DWO_ISO_C` fallback; ASan (+TSan from plan 4) gates.

### `crates/` — the Rust runtime (active, retiring on parity)

Unchanged from CLAUDE.md's description: `rt` is the monolithic Stage-2 runtime producing the `wo` binary; the 14 unprefixed siblings (`ql`, `value`, `engine`, `txn`, `db`, `wal`, `sub`, `http`, `gen`, `policy`, `logic`, `service`, `ui`, `app`) are phase scaffolds. **Retirement path:** stays authoritative until the C stack passes the parity harness (plan 3 task 7, plan 6 blog smoke); then moves under `.dev/reference/` the way v1 did. Until that day, nothing here is refactored to accommodate the C track.

### `tests/`, `scripts/`, `client/` — the proof layer (target)

- `tests/corpus/` — the conformance spine (plan 3): `run/`, `compile-fail/`, `trap/`, then `gc/` (plan 3), `db/` (plan 5), `actor/` (plan 4), `sys/` (plan 9), `sample-logwatcher/` (plan 10), `lang/` (plan 8). Exact-outcome matching: byte-equal stdout, exact `WO-E###`, exact trap code.
- `scripts/` — `oop-e2e.sh` (corpus runner), `oop-parity.sh` (Rust-overlap manifest runner).
- `client/` — `wo-live.js`, the hand-written no-framework live-patch runtime (plan 7).

### `prototypes/` — reference implementations (frozen)

- `wo-db/` — the ~2k-line C++ query-layer prototype (SQL + Cypher + document paths). Stays: it is the semantic reference plan 5 cites. `make test` must keep passing.
- `wo-rt-c/` — ⚠ **stale duplicate.** The content moved to root `runtime/` (both are currently git-tracked). Slated for deletion once the user confirms nothing references it; `justfile`/doc references already point at `runtime/`. Nothing new lands here — repo rule: prototypes receive nothing new.

### `.dev/reference/` — read-only study material

- `crates/` — the 13 v1 `wo-*` crates, a nested Cargo workspace (build with `cd .dev/reference/crates && cargo build`). Preserved per the wo-seg migration plan ([`runtime/database/07-wo-seg-migration.md`](runtime/database/07-wo-seg-migration.md)).
- `colibri/`, `llama-cpp/` — vendored study trees (zero-dep C inference engine; MoE runtime) — see [`.dev/reference/colibri/`](.dev/reference/colibri/).
- `linux/`, `go/` — per-developer symlinks to kernel and Go sources (gitignored; recreate per `CLAUDE.md`).
- `rest/` — `.rest` HTTP files driving manual smoke against a running runtime; plan 6's blog smoke scripts the same sequences.

### `docs/` — all documentation

```
docs/
├── 01…08-*.md           numbered design docs (this file is 08)
├── writeonce-pl.md      language positioning
├── runtime/             user-facing language overview + the 7-phase database series
├── examples/            blog/, ecommerce/, pricing/ samples; ⏳ log-watcher/ (plan 10)
├── plan/                numbered engineering plans 00–16, linux/ cards, assembly/,
│   ├── exploration/     c-runtime/ (A–F, done), ui/ (htmlx track), colibri/
│   └── oop-vm/          ⏳ the OOP-track contracts: 00-wob-format, 01-error-catalog,
│                        02-corpus, 03-shard-actor, 04-db-binding, 05-http-service,
│                        06-ui-live, 07-systems-stdlib
├── superpowers/
│   ├── specs/           the two approved track specs (2026-08-01)
│   └── plans/           implementation plans 1–10 (2026-08-01, prose-only)
└── future-scope/, cm.md legacy notes
```

Repo rule restated: documentation belongs here; code directories keep one orientation README each.

### v1 blog operating assets — `content/`, `data/`, `wo-data/`, `static/`, `templates/`, `infra/`

The original writeonce blog's articles (`content/`), its data directories, `.htmlx` templates (`templates/` — cited by the UI track as concrete v1 usage), static files, and deploy config. Governed by the wo-seg migration plan; untouched by the OOP/systems tracks except as reference. `target/` is cargo build output (ignored).

### `.dev/` — developer-local state

Gitignored symlinks into per-machine AI-tooling state plus `commit.md`, the running commit-message draft (the user commits; agents only append drafts). See `.dev/README.md`.

## Lifecycle: how the shape evolves

| Stage | What changes at the root |
| --- | --- |
| Today | `runtime/` holds wo-rt.c; `crates/rt` serves Stage 2; plans are paper. |
| After plans 1–3 (milestone 1) | `compiler/` + `runtime/src/` + `tests/corpus/` + `scripts/` exist; `woc build` emits single binaries; `prototypes/wo-rt-c` deleted. |
| After plans 4–7 | `runtime/src/` carries shard/db/http/ui modules; `client/` exists; the C stack serves the blog sample end to end. |
| After plans 8–10 | systems stdlib in `runtime/src/sys_*`; `docs/examples/log-watcher/` proves program mode. |
| Parity | `crates/` moves to `.dev/reference/crates-v2/` (naming decided then); the `wo` toolchain name transfers to the C stack; Cargo.toml shrinks accordingly. |

## Build sequence

The order the project completes, with the two parallel windows made explicit:

1. **`runtime/` VM core** — plan 1 (`.wob` format + `wovm`: memory model, loader, interpreter). No dependencies; the format doc it pins is everyone's contract.
2. **`compiler/` front** — plan 2 (`woc`: lexer→parser→types→owner). Independent of plan 1 — *may run in parallel with it*; needs `apt install ocaml dune`.
3. **Emit + end-to-end** — plan 3 (bytecode emitter, conformance corpus, `woc build` single binary, acceptance gate). Needs 1 + 2. **Milestone 1 done here.**
4. Two tracks fork and *can proceed in parallel*:
   - **Server track (sequential within):** plan 4 shard-actor runtime → plan 5 DB engine binding → plan 6 HTTP service layer → plan 7 UI/.htmlx/LIVE.
   - **Systems track (sequential within):** plan 8 Haxe-parity language → plan 9 program mode + stdlib → plan 10 log-watcher sample. Only seam with the server track: the JSON codec shared between plans 6 and 9 (either lands it, noted in both).
5. **Parity + retirement** — parity harnesses green (plans 3/6), then `crates/` (Rust) retires to `.dev/reference/` and the `wo` name transfers to the C toolchain.

Rule of thumb: `runtime → compiler → emit → {shard → db → http → ui} ∥ {language → stdlib → sample} → parity`.

## Naming conventions (recap)

- New runtime crates: unprefixed (`ql`, `db`, …). V1 crates: `wo-` prefixed, in `.dev/reference/crates/`.
- Binaries: `wo` (Rust toolchain today), `woc` (OCaml compiler), `wovm` (C VM); at parity the `wo` name moves to the C toolchain.
- C prototype directory names keep their historical `wo-` prefixes (`wo-db`).
- Plan/spec files: `YYYY-MM-DD-<topic>.md` under `docs/superpowers/{specs,plans}/`; numbered engineering plans under `docs/plan/`.