# SINGLE-WRITE EMISSION — JIT plan (paper stage)

todlando, 2026-08-29. Authored on doyle's call after the v0.65.0 cut: **paper-prep only — no
cargo, no pool, no build.** Every number here is read from source at a sha or from the
toolchain's own std sources; nothing was executed. The lane gets its pool when deployah
source-verifies the counter-100 publish and ir66 reaps.

## 1. The defect, stated as a property rather than a story

A diagnostic line that a test parses (`TOKEN:...`) is emitted today with `eprintln!`. Where the
line interpolates anything, std issues **one write syscall per format fragment**, so a reader on
a shared stderr can observe a line torn between fragments — and the trailing `\n` is itself a
separate fragment, so a torn line can be completed by *another process's* newline.

**Measured at the toolchain's own std source** (`stable-x86_64-pc-windows-msvc`, 1.96 —
`library/std/src/io/stdio.rs`, `library/std/src/io/mod.rs`), not asserted from memory:

- `Stderr` is documented "This handle is not buffered" and is
  `&'static ReentrantLock<RefCell<StderrRaw>>` (stdio.rs:892). No buffering ⇒ no coalescing.
- `Write::write_fmt` (mod.rs:1990) has a fast path: `args.as_statically_known_str()` ⇒ ONE
  `write_all`. Otherwise `default_write_fmt`.
- `default_write_fmt` (mod.rs:615) drives a `fmt::Write` adapter whose `write_str` calls
  `inner.write_all(...)` **per fragment** (mod.rs:628). Fragments = literal pieces + each
  formatted arg + the trailing newline.
- The `ReentrantLock` serializes *threads of one process*. It is not a cross-process lock, and
  the daemon's children inherit the same stderr handle — which is exactly the population the
  census's 26 consumer test files read.

⚠ The 43 static-literal sites are single-write **only because of that `as_statically_known_str`
fast path**. That is a std implementation detail, not a contract. The property must be owned by
our emitter, never inherited from the standard library's current optimizer.

## 2. Population — measured at the cut sha `4d6007ac` (tag v0.65.0 == main == golden r4 head)

| | count |
|---|---|
| `TOKEN:`-shaped emission sites in `crates/*/src` | **487** |
| ...of which INTERPOLATED ⇒ multi-write today | **444** |
| ...of which static-literal ⇒ already one write (by std's fast path) | **43** |
| distinct tokens | 383 |
| consumer test files that parse a token off an inherited-stderr surface | 26 |
| **macro calls that span multiple lines** | **200** |

By crate: spt-daemon 270, spt 195, spt-runtime 8, spt-live 5, spt-net 5, spt-store 4.
By macro: eprintln! 485, println! 1, eprint! 1.

The single `println!` is `reporting.rs:428 DRIVEN_BY` — it goes to **stdout**, is not on the
stderr tear surface, and is not this lane's business.

**200 multi-line calls is the number that shapes the work**: any sed-shaped or regex-shaped
mass rewrite silently mangles 41% of the population. The conversion is per-site and reviewed,
or it is not done.

## 3. Requirement — NEW-REQ-FIRST

`grep -iE "atomic|single.write|whole.line|tear|interleav"` over `traceable-reqs.toml` returns
nothing covering emission. Per AGENTS.md rule 3 the REQ is minted **before** the code.

Proposed:

- **id**: `REQ-EMIT-SINGLE-WRITE`
- **title**: A machine-parsed diagnostic line is handed to the OS as exactly ONE write of the
  complete rendered line INCLUDING its newline. The property is deterministic and belongs to
  the emitter: it is a statement about how many writes we issue, NOT a claim that any OS makes
  a write atomic. POSIX gives pipe writes at or below PIPE_BUF atomicity; Windows gives no such
  guarantee; a file append and a console are different again. We therefore promise the thing we
  control and refuse to promise the thing we do not.
- **required_stages**: `["impl", "unit"]` at activation. `doc` rides only if a published surface
  states the format — an undiscoverable shipped surface reads as missing, so if the guarantee is
  meant to be relied on by adapter authors the docs clause is a deliverable of the fix, not a
  nicety.

## 4. Shape — the prototype already exists in the tree

`crates/spt/src/roster.rs:335-355` (my #240 lane) is exactly the target shape and its comment
already states the reasoning: a **pure function composes the whole line into a `String` ending
in a newline**, and the caller does **one `write_all`**. Composing purely is what makes the text
unit-pinnable without reaching through a `Once`.

Generalize it, do not copy it 444 times:

- The emitter lives in **`spt-proto`** — measured to be the dependency root (`spt-proto` has no
  `spt-*` dependencies; spt-store, spt-runtime, spt-msg, spt-net, spt-live, spt-daemon and spt
  all depend on it directly). No new crate, no layering change, one edge that already exists.
- A macro (`spt_emit!` / name TBD at design) that formats its arguments, appends the newline if
  the caller did not, and issues ONE `write_all` on a locked handle. There are **zero**
  `macro_rules!` in `crates/*/src` today, so this introduces the first — call that out in
  review rather than sliding it in.
- The handle is a parameter, not a hardcoded `stderr()`, or the property is untestable (section 5).

## 5. Validation — the deterministic emitter property, NEVER a CI rate

The gate is a unit test against an **instrumented writer** that counts `write`/`write_all`
calls and records each buffer:

1. render a line with N interpolated arguments through the emitter;
2. assert the writer saw **exactly one** call;
3. assert that one buffer **ends with the newline** and equals the fully rendered line;
4. assert the same for a static-literal line, so we do not silently depend on std's
   `as_statically_known_str` fast path;
5. a RED-FIRST arm: the same assertions against a plain `write_fmt` path must FAIL (a
   multi-fragment count), proving the test can distinguish the two — otherwise it is an arm that
   cannot fail, which is the v0.65.0 arc's head-1 lesson.

**Explicitly out of bounds as validation:** re-firing CI and reading a tear rate. The only
tear-site observation in the record is deployah's four complete SUBSCRIBE_DECISION lines from
run 33236164340 — a zero. A rate that is zero before the fix cannot demonstrate the fix, and
hertz has made no rate claim; do not attribute one to him.

## 6. Sequencing

- **W0 (paper, this doc)**: premise measured, population counted, REQ drafted, shape chosen.
- **W1**: mint `REQ-EMIT-SINGLE-WRITE` in `traceable-reqs.toml`; land the `spt-proto` emitter +
  its unit battery incl. the red-first arm. `traceable-reqs check` must pass before anything
  converts. ⚠ Re-run `check` immediately after the hand-edit — exit 2 means the registry did not
  PARSE and nothing was checked, and every reading since the bad edit is vacuous; keep double
  quotes out of the REQ title.
- **W2..Wn**: convert by crate, smallest first — spt-store 4, spt-live 5, spt-net 5,
  spt-runtime 8, then spt 195, then spt-daemon 270. Per-site and reviewed; the 200 multi-line
  calls are why. Fix the POPULATION, not the instance: a crate is done when it has no remaining
  `TOKEN:`-shaped `eprintln!`, and the census generator (parked beside the cut artifacts) is the
  meter for that.
- The 26 consumer test files are the blast radius to re-read after each wave.

## 7. Not in this lane, but must be said in the same breath

`IDLE`, `DISPATCH`, `BUSY`, `BOUND` are single common words matched as **substrings** by the
tests that parse them. A whole-line-write fix does nothing for those — they need anchored
matching. Different defect, same files. It is recorded here so it is not rediscovered as a tear
and mis-attributed to this lane.

## 8. Honest state

Nothing is built. The premise is read from std source and the population from the repo at a
sha; neither has been executed. The first thing the lane does when it gets a pool is prove the
premise by measurement — the instrumented writer showing N writes for an interpolated
`eprintln!` and 1 for the emitter — because a design premise measured only by reading is a
hypothesis, and this project has paid for that mistake before.