ww/docs/test-system-v2.md

# WW test architecture

Status: active architecture as of 2026-08-07. The target graph, corpus
accounting, and complete `test-commit` gate have been rechecked, including its
two concurrency controls separately and together. The separately gated
byte-identity and test-infrastructure proofs have also run. Bootstrap and
platform proofs have not run as part of this revision.

## Why the old suite was slow

The former suite made shell, Make, and one C executable per legacy case share
ownership of discovery, registration, phase selection, scheduling, result
records, timeout classification, and a last-green cache. Language behavior and
byte-identity loops repeatedly rebuilt complete package graphs. The measured
serial result was 411.403 seconds wall time, with a static lower bound of about
11,040 compiler-stage processes and 4,800 archive creations.

The replacement assigns each assertion to one owner and keeps expensive proof
categories out of the ordinary developer target.

## Owners

| Category | Owner |
| --- | --- |
| Arena, lexer, parser, checker, narrow codegen | Five in-process C unit binaries |
| Compile success/rejection, stage-routed diagnostics, and runtime exit | `test/wcc/data/*/case.ww`, executed by `wwfixture` |
| Package semantics | `test/package` and the native package-test coordinator |
| Language behavior | `test/lang/*_test.ww` through the language `@test` runtime |
| Library behavior | Library-owned `@test` sources named by `LIBRARY_TESTS` |
| Standalone library-source compilation | Four real source paths named by `LIBRARY_STANDALONE_SOURCES`, compiled directly by both frontends |
| Compiler-output identity | `test-lang-byteid` and `test-data-byteid` plus residual byte/artifact carriers |
| Fixed point and self-host | `test-bootstrap` |
| Host linker/platform behavior | `test-platform` |

The live declarative compiler corpus has 1,495 fixtures and 2,990 C/WW cells:
338 expected rejections (314 shared and 24 stage-specific), 17 compile-only
successes, 198 exit-zero programs, and 942 explicit-exit programs.

133 native C carriers remain. They are partitioned exactly once as five
in-process units, 10 byte/artifact gates, six bootstrap gates, one platform
gate, and 111 residual compiler, package-layout, ABI, diagnostic-observer,
driver, linker, or FFI gates. Rows migrated to fixtures or native `@test`
owners were removed from those carriers; there is no compatibility execution
path for retired rows. 74 former byte/artifact carriers whose only assertion
was a cstage-vs-wwstage `.s` byte-compare of sources now living in the
corpus were retired into the blanket `test-data-byteid` comparator (the
last 13 had their remaining inline sources added as fixtures first); the
survivors observe something the blanket cannot: assembly patterns, symbol
tables, `.wwi` round-trips, or the wwstage-driver leg. Wwstage-driver-leg
byte identity (`ww_ww` versus `ww` over the emitted `.s` set) has one
owner, now ww-native: `test/byteid/libbyteid_test.ww` on the
`test/testenv` helper package, whose unit sweep spans the 44-entry lib
roster (test fixtures, sentinel-guarded import probes, a zero-dep
root-only build) plus the lib/ completeness scan; the former 815/940/951
driver-parity carriers were folded into it, their content identity
already owned by their corpus twins, and the native `989_lib_byteid.c`
carrier retired with the port.

## Carrier endgame

The declarative corpus and the native `@test` owners are the permanent
test surface — the `go/test/` analogy. The native C carrier fleet is the
pre-Go-1.5 artifact and shrinks toward exactly two terminal classes:

1. **C-bootstrap observers.** The five in-process units watch the C
   frontend from inside its own process and are irreplaceable while
   `cmd/` is the live frontend. The six bootstrap gates are the same
   class's proof column: they compare the wwstage tools against the C
   stage to a fixed point. At the eventual selfhost flip both freeze
   into a bootstrap smoke gate (Go 1.5 deleted its C toolchain and that
   toolchain's tests; it did not port them).
2. **Host ABI/platform gates.** Behavior owned by the host linker,
   loader, or ABI (`996_dyn_ww` today). These observe the platform, not
   the compiler, and stay native exactly as long as the claim is about
   the platform.

Everything else gets a ww owner. Byte and artifact observations —
assembly-pattern greps, symbol tables, frame layouts, `.wwi`
round-trips, driver-leg comparisons — are subprocess plus file IO plus
string search, which `test/package/package_test.ww` already performs
natively (runcommand + in-language assertions). A C carrier whose
assertions fit that shape is ported and retired in the same commit,
assertions preserved or strengthened, with no compatibility execution
path left behind. A carrier that is merely historical is deleted
outright; git history is the archive.

## Public targets

| Target | Composition |
| --- | --- |
| `test` | Five in-process units plus one compile-only C/WW compiler-fixture smoke case |
| `test-compiler` | Complete fixture corpus plus residual compiler/integration carriers |
| `test-package` | Package planning, grouping, routing, and package runtime only |
| `test-lang` | Language-owned `@test` behavior |
| `test-library` | Library-owned `@test` behavior plus four direct standalone-source C/WW compilation checks |
| `test-commit` | Unit + compiler + package + language + library behavior |
| `test-byteid` | Compiler-output identity gates |
| `test-bootstrap` | Fixed-point bootstrap plus the 950/991–995 native gates |
| `test-platform` | Host-dependent dynamic-link gate |
| `test-wwfixture` | Fixture CLI/process/protocol integration boundary |
| `test-all` | Commit + byte-ID + bootstrap + platform + test-infrastructure checks |

`test-commit` deliberately excludes byte identity, bootstrap, and platform
work. `test` is intentionally smaller than the old target and is the ordinary
developer feedback gate. Its purpose is a short, direct path from a compiler
edit to useful evidence, not compliance with an arbitrary wall-clock cutoff.

Make and fixture scheduling have separate, explicit owners. The Makefile does
not detect CPU count or add `-j` to `MAKEFLAGS`; the caller selects Make
parallelism with the standard `make -jN` option. `JOBS ?= 1` controls only the
`wwfixture -j N` value passed by `test-compiler`. A normal fast gate can use
both layers deliberately:

```sh
make -j4 JOBS=4 test-commit
```

For deterministic failure reproduction, make both layers serial explicitly:

```sh
make -j1 JOBS=1 test-commit
```

Serial execution is a debugging mode, not a correctness requirement. `JOBS`
is not inferred from `MAKEFLAGS`, and there is no jobserver adapter or second
scheduler hidden in Make.

`nocc` remains the separate, explicit reproduction route from a checked-in
stage-0 snapshot. It is not an implicit prerequisite of ordinary tests or of
`test-bootstrap`, because it has an external stage-0 precondition.

## Compiler fixtures

Each fixture is one directory with one `case.ww`. Its first line is exactly one
of:

```text
//ww:error "required diagnostic fragment"
//ww:error c "C-stage fragment" ww "WW-stage fragment"
//ww:compile
//ww:run
//ww:run-exit N
```

- `error` requires normal nonzero frontend termination and the declared stderr
  fragment. The labeled form routes distinct fragments to the C and WW cells;
  labels are fixed-order and neither fragment is treated as a shared fallback.
- `compile` requires frontend exit zero and produces no executable.
- `run` builds and requires normal program exit zero.
- `run-exit N` builds and requires normal program exit `N`.

Every fixture is run against the C and WW frontends. Signals, launch failures,
timeouts, build failures, and runtime exits are distinct outcomes.
`test-compiler` passes `-j $(JOBS)` and therefore uses one fixture slot by
default. The direct `wwfixture` CLI retains its own four-slot default; pass
`-j N` when its concurrency must be explicit. Its existing
`os.exec.start`/`poll` loop supervises the independent processes. Each cell has
its own working directory; filesystem fixtures use that directory or an
existing `temp.named` path rather than a shared fixed pathname.

The old `TESTS` list and all explicit per-wrapper Make rules are gone. A
surviving C carrier is registered only by its source file and built through one
generic pattern rule. Four arena/frontend units share a static rule; the codegen
unit links the existing private `cgen` and text-emitter objects directly.

`test/wwfixture/integration.sh` remains the direct black-box owner for behavior
that exists only at the command/process/protocol boundary: filtering and list
output, phase and outcome classification, diagnostic routing, malformed-corpus
and identity-drift rejection, signal/timeout/interruption cleanup, publication
failure, and strict result-stream decoding. Semantic fixtures cannot prove
those observations about their coordinator. `test/wwfixture/process/main.ww`
owns the lower-level `os.exec` primitives, not the CLI policy layered over
them, so it is complementary rather than a duplicate owner.

The five unit sources have zero active `system`, `popen`, `fork`, or `exec`
calls. Before direct conversion they contained two `popen` call sites and a full
`test-unit` run launched one `ww -V` plus twelve `w6c` processes. `400_w6c` now
checks the same twelve assembly fragments in process, grouped under ten unique
sources. The CLI version assertion lives with C/WW-driver parity in the existing
`949_driver_flagargs` integration carrier; `000_smoke` retains its arena-growth
and nonempty-version-constant assertions.

## Package and language behavior

`ww test` delegates directory package requests to the native package
coordinator. The coordinator owns discovery, package grouping, same-package and
external-package test composition, filtering, result aggregation, and its
internal temporary workspace. With `-c`, it publishes each exact
`<package>.test` binary and adjacent `<package>.test.sepwork` tree in the
package directory; those become caller-owned artifacts. Without `-c`, it
removes the temporary binary and scratch with its workspace. The language
runtime owns individual `@test` functions.

Separate compilation is the only driver build path; no compatibility mode
switch remains.

`ww build`, an explicit single-file `ww test -o <stem>`, and each successful
directory-package `ww test -c` build publish `<stem>.sepwork` as a caller-owned
artifact directory. The driver acquires it with one fresh `mkdir` and refuses
an existing path; it never clears a collision. A caller keeps only the exact
artifacts it observes and removes that exact tree on every later success or
failure. `ww run` and no-output single-file `ww test` use driver-owned scratch
instead; both driver stages place that scratch and their temporary executable
beneath one freshly acquired directory, remove both after every build result,
and make cleanup failure fail the command. Make recipes build driver-produced
tools in invocation-owned directories and apply the same exact cleanup rule.

`ww build -w DIR` and single-file `ww test -w DIR` replace that scratch with a
caller-owned persistent package-artifact workdir: the directory must already
exist, is never cleaned by the driver, and holds one committed unit, `.wwi`,
`.s`, `.o`, and dep `.a` per package plus byte copies of the compiler and
assembler and a small mode stamp. A package is reused only when its freshly
composed unit byte-equals the committed unit and the recorded tool copies
byte-equal the live tools — content identity only, no mtimes, no hashes, every
decision reproducible with `cmp` against plain files. Recompiled artifacts
land at staged `.new` names and commit by rename with the unit renamed last,
so an interrupted build forces a recompile rather than a false reuse; the
link always reruns. One workdir serves one invocation at a time and one
(root, mode) shape; both driver stages implement the identical contract.
This is build staleness in the Make/mk/Go sense, not a result cache: tests
always run, and the byte-identity and bootstrap gates keep building on fresh
scratch. `make clean` reclaims every workdir under `out/`.

`test/lang` currently uses one package per source file, so its complete gate
still performs independent package builds. That remaining source layout is not
hidden behind caching or concurrency; it is outside the small `test` target.

## Compiler-only byte identity

`ww build -S` and `ww test -S -o <stem>` run source discovery, dependency
ordering, unit composition, and each required `w6c -c` invocation. They return
after the complete `.s`/`.wwi` set exists. The producer loop does not invoke
`w6a`, create per-package archives, or invoke `w6l` when `-S` is active.

`test-lang-byteid` runs the 158 selected language files once with C `w6c` and
once with WW `w6c`, requires identical emitted `.s` filename sets including
`__root.s`, and compares those bytes. Relative to the old two-leg full builds,
this removes at least 3,476 assembler launches, 3,160 archive writes, and 316
linker launches from the comparison loop. A cold Make invocation may still
build prerequisite compiler binaries; the compiler-only claim applies to the
per-language-file comparison path.

`test-data-byteid` applies the same comparator to the declarative corpus:
every non-error `case.ww` builds twice through the fixed cstage driver with
only `WW_W6C` swapped, and every emitted per-package `.s` must be
byte-identical. `//ww:error` fixtures have no `.s`; their both-stage reject
parity is owned by the fixture corpus itself. Known cs/ww divergences are
pinned in `DATABYTEID_DIVERGED` with the `989_lib_byteid` discipline: a
pinned fixture must still build on both stages and still differ, so a
compiler fix fails the gate demanding graduation rather than silently
widening coverage. The full sweep compares the 1,157 non-error fixtures
in about a minute and is scratch-rooted under `out/`, not `/tmp`.

Byte identity is an explicit proof gate. It is not a prerequisite of `test` or
`test-commit`.

## Bootstrap, subprocesses, and CSP

Stage-2-through-stage-4 fixed-point proofs and the 950/991–995 self-host gates
are reachable through `test-bootstrap` and `test-all`, never through `test` or
`test-commit`. Cold ordinary targets may still build their C- and WW-stage tool
prerequisites once; they do not iterate those tools to a fixed point. The C
bootstrap source and the standalone `nocc` route remain intact.

The bootstrap recipe owns the fixed `out/bootstrap` tree. Make schedules that
target once within one invocation, but two independent `make bootstrap`
invocations are not safe to run concurrently and remain mutually exclusive.

`lib/os/exec` is the sole reusable WW subprocess mechanism. Fixture and package
coordinators use its captured asynchronous path. The WW driver directly uses
`os.exec.runstdio` for inherited-stdio, inherited-environment, leader-only
compiler, assembler, linker, cleanup, run, and single-file-test calls. The
local WW `procrun` implementation is deleted. The C bootstrap retains its C
process implementation because it cannot consume a WW standard-library
module.

WW has tokens and an opaque type for future CSP/channel work, but no mature
production channel operations, task runtime, or scheduler. No channel,
goroutine, thread, worker-runtime, or CSP library was added. Coordinators stay
single-threaded; OS process polling does not require language-level threads.

## Retired mechanisms

The following are deleted, not adapted:

- `test/run`, including its phase classifier, `xargs` scheduler, atomic private
  records, timeout-text classifier, result collector, and last-green cache;
- `test/run_test.sh`, the synthetic shell tests for that protocol;
- every explicit `TESTS` registration and all 329 explicit wrapper rules;
- the unregistered `test/runww.ww` corpus runner;
- frozen duplicate compiler-corpus code under `internal/wwtest`, `test/wwtest`,
  and `test/compiler`;
- the redundant standalone `smoke`, `test-run`, and `test-harness` routes; and
- library-launcher wrappers whose only assertion was an existing `@test`
  source's exit status, including the declarative `900_stdlib.c` launcher.

There is no test cache, daemon, scanner, generated manifest, database, new
framework, compatibility API, concurrency runtime, dependency, or changed
timeout policy in this architecture.

## Open driver work

Carried over from the dissolved project plan; each is deliberate scope, not
drift:

- Recursive package discovery (a `./...`-equivalent pattern) for `ww test`.
- Package-level concurrency for the coordinator's builds (it is
  single-threaded by design today).
- A package-level `-o` contract (single-file `ww test -o` exists; directory
  packages publish fixed `<package>.test` stems under `-c`).
- Universal `*_test.ww` filename migration for library tests (several
  library suites still use the older `*test.ww` names, enumerated by
  `LIBRARY_TESTS` and the `989_lib_byteid` roster).
- The remaining invalid-`@test` attribute-shape diagnostics (exported
  tests, prototypes, arguments, variadics, non-void returns, duplicate
  annotations) with stable text in both frontends.

## Validation policy

Use `test-unit` as the inner loop for lexer, parser, checker, and narrow codegen
changes. Run `test` for the ordinary local compiler check, followed by the
focused owner for the changed behavior. Use `test-commit` for ordinary
pre-commit behavior; use `make -j4 JOBS=4 test-commit` when parallel feedback is
desired, and `make -j1 JOBS=1 ...` to reproduce failures deterministically.
Run `test-byteid` and `test-bootstrap` only when those proof categories are
intended. `test-all` is the exhaustive CI/release composition and should not be
launched casually.