docs: disambiguate the daisy/daisy collisions the rename left in dev/, refresh the REFACTOR roadmap, merge the split CHANGELOG headings

[rhoadesScholar]

Why

The blanket gerbera -> daisy rename in 2c1a382 renamed both sides of every comparison in dev/. The two documents whose entire purpose is to compare the upstream Python library with this rewrite now compare daisy with daisy:

Where	Reads today
dev/MIGRATION_REPORT.md:1	# Migration Report: daisy → daisy
dev/MIGRATION_REPORT.md:7	the comparison table header names both columns Daisy Test
dev/INTERNAL_DIFFERENCES.md:1	# Internal Differences: daisy vs daisy
dev/INTERNAL_DIFFERENCES.md:9,20	two adjacent paragraphs, both **Daisy**:, describing a tornado poll loop and a tokio::select! loop — 11 sections like this
dev/INTERNAL_DIFFERENCES.md:30	**Pro daisy**: … daisy wastes CPU …; daisy's select is free.
dev/REFACTOR.md:188	… composes with per-task max_workers, which daisy doesn't have.
dev/REFACTOR.md:98	… since I haven't started using daisy as a replacement for daisy

This is institutional memory that is currently unreadable, so the fix is disambiguation, not deletion. Nothing is removed.

What

1. Disambiguate to the convention this repo already states. docs/source/design/index.md:30 says "daisy 1.x" refers to the upstream Python library that daisy v2 is a rewrite of. "daisy v2" (or just "daisy", in unambiguous contexts) refers to this codebase — and PROTOCOL.md, PIPELINES.md, WORKER_SHUTDOWN_FLOWS.md already use it. Every colliding occurrence in the three dev/ docs now reads daisy 1.x or daisy v2.

The sides were not guessed. git show 2c1a382^:<file> still has the pre-rename text, where the old side reads daisy and the new side reads gerbera, so the mapping is mechanical. See the check below.

2. dev/REFACTOR.md roadmap: mark 2.8 / 2.2 / 2.4 landed, each with a pointer, verified against this tree:

• 2.8 lazy roots — root_iter_owned + LazyBlockIter (daisy-core/src/dependency_graph.rs:468, :705) feed DependencyGraph::roots (:606), which now returns Box<dyn Iterator<Item = Block> + Send>.
• 2.2 per-block timeout — landed, but not as the recorded decision describes. The decision says "Default timeout = None (no timeout)" and "daisy can't actually preempt a running Python function inside a thread". Today every block has a timeout, it defaults to 600 s and cannot be disabled (daisy-py/src/py_task.rs:104), and it does preempt: the subprocess worker self-kills at the deadline (daisy-py/python/daisy/_subprocess_worker.py:70). The entry says that rather than implying the plan shipped as written.
• 2.4 JSON observer — JsonProgressObserver (daisy-py/python/daisy/_progress.py:267), exported from daisy, covered by tests/test_json_observer.py.

The Problem/Proposal/Next Steps/Decision discussion in each numbered section is left untouched — it is the record of the decision, not a status field.

3. CHANGELOG.md [Unreleased]: one heading per category, in Keep a Changelog order. The reported defect was two ### Fixed split by an intervening ### Documentation and ### Changed; the section had in fact accumulated 16 headings (5× Changed, 5× Added, 2× Fixed, 2× Removed, 2× Documentation). It is now Added / Changed / Removed / Fixed, the order the file's own header commits to, with the project's non-standard Documentation category last. Bullets are moved, never rewritten — see the byte-level check below.

Verification

Docs-only, so there is no failing→passing example to show; the meaningful checks are that the sides are right and that no content was lost.

The sides. Reconstruct each file from its pre-rename ancestor by substituting gerbera → "daisy v2" and daisy → "daisy 1.x", then diff against this branch:

$ for f in MIGRATION_REPORT INTERNAL_DIFFERENCES; do
    git show 2c1a382^:$f.md | python3 -c "…gerbera->daisy v2, daisy->daisy 1.x…" > exp_$f.md
    echo "--- $f: diff pre-rename-with-sides vs HEAD ($(diff exp_$f.md dev/$f.md | grep -c '^[<>]') differing lines)"
  done
--- MIGRATION_REPORT: diff pre-rename-with-sides vs HEAD (0 differing lines)
--- INTERNAL_DIFFERENCES: diff pre-rename-with-sides vs HEAD (18 differing lines)

dev/MIGRATION_REPORT.md is now byte-identical to the pre-rename file under that substitution — zero differing lines. INTERNAL_DIFFERENCES.md's 18 differing lines are all places where v2.0 has legitimately moved since the rename, not label choices: the section 4 rewrite for subprocess-only workers (the **Parity**: paragraph, the python -m daisy._subprocess_worker bullets, the "Earlier v2 builds…" paragraph), two whitespace fixes inside code blocks, and one sentence I reworded — line 3, "how the two implementations differ" → "how daisy 1.x and daisy v2 differ".

No CHANGELOG content lost. Every non-blank, non-heading line, sorted, before vs after:

$ git show origin/v2.0:CHANGELOG.md | grep -v "^### " | grep -v "^$" | sort > old.txt
$ grep -v "^### " CHANGELOG.md | grep -v "^$" | sort > new.txt
$ diff old.txt new.txt
266c266
<   `worker_processes=False`; see the Removed section above for why it went.)
---
>   `worker_processes=False`; see the Removed section below for why it went.)

One line differs, and it has to: that bullet points at the Removed section, which the reorder moves from above it to below it.

Tests. The change touches four .md files and nothing else (git show --stat below), so it cannot affect them. cargo test -p daisy-core is cheap and green on this branch:

$ cargo test -p daisy-core
running 63 tests
test result: ok. 63 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s
running 8 tests
test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.18s
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

pytest tests -q needed a detour worth reporting separately (below); once funlib.geometry is present it is green on this branch:

$ uv run pytest tests -q
241 passed, 2 skipped, 1 xfailed, 35 warnings in 38.17s

Judgment calls, flagged so they can be rejected individually

1. Two bullets moved out of ### Documentation. Consolidating forces a category for every bullet, and two under the second ### Documentation heading were not documentation: "Worker starts are now bounded by a hard per-task budget…" (a behaviour fix — "respawned forever and the run never terminated") → Fixed, and "Block functions run in worker subprocesses." (an execution-model change) → Changed. Leaving them under Documentation while claiming to have ordered the file seemed worse. Happy to put them back.
2. above → below in the thread-execution bullet, forced by the reorder (see the diff above).
3. dev/REFACTOR.md Part 3 is disambiguated too, slightly beyond the two documents named in the title's spirit — bullets like "which daisy doesn't have" and "Daisy's restart-cap is respawn forever, hope it works" are the same collision from the same commit, in a file this PR already edits.
4. Two stray blank lines removed from the top of dev/REFACTOR.md, also introduced by 2c1a382.

Not touched (pre-existing, reported rather than folded in)

• dev/INTERNAL_DIFFERENCES.md §11 Performance still describes daisy v2's workers as threads ("daisy v2's thread-based workers have negligible startup cost", "daisy v2's thread spawn costs ~0.005s"). Those benchmarks predate the subprocess-only migration, so the numbers and the prose need a re-run, not a relabel. I only fixed which side each column names.

• dev/REFACTOR.md:187 points at docs/ABANDONMENT.md; the file now lives at docs/source/design/ABANDONMENT.md. Its Part 3 also still credits "Run-stats with linear regression slopes", which [Unreleased] records as removed.

• funlib.geometry is an undeclared dependency. daisy-py/python/daisy/v1_compat.py:120,127 imports it (lazily, inside the compat Block.read_roi / write_roi getters) and three test modules import it directly, but it appears in neither [project] dependencies nor any dependency group. On a clean uv sync at origin/v2.0, pytest tests -q aborts collecting tests/test_block_compat.py with ModuleNotFoundError: No module named 'funlib', and with that module ignored 42 tests fail — every distributed test, because the worker subprocess hits the same import error (daisy worker subprocess exited with code 1 / ModuleNotFoundError: No module named 'funlib' → task 'preempt-fast' was abandoned). Identical counts with and without this PR's changes:

  ### BASELINE (pristine origin/v2.0, 542c3c2, no local edits: 0 modified files)
  42 failed, 170 passed, 2 skipped, 1 xfailed, 25 warnings in 33.85s
  ### WITH DOCS CHANGES (4 modified files, all .md)
  42 failed, 170 passed, 2 skipped, 1 xfailed, 25 warnings in 35.90s
  

  uv pip install funlib.geometry alone turns that into 241 passed, 2 skipped, 1 xfailed. There is no test workflow in .github/workflows/ (docs, lint, publish only), which is presumably why this is invisible. Worth its own one-line PR adding funlib.geometry to dependencies — happy to open it.

$ git show --stat --oneline HEAD
6e35d28 Disambiguate the daisy/daisy collisions the rename left in dev/
 CHANGELOG.md                | 277 ++++++++++++++++++++------------------------
 dev/INTERNAL_DIFFERENCES.md |  94 +++++++--------
 dev/MIGRATION_REPORT.md     |  30 ++---
 dev/REFACTOR.md             |  42 ++++---
 4 files changed, 214 insertions(+), 229 deletions(-)

CI: ruff is red on this PR and red on the base

The ruff job fails with 28 errors, all in tests/ (I001 import sorting, E402, …). This PR changes four .md files and nothing else, so it cannot be the cause — and the base agrees:

$ git diff origin/v2.0 HEAD --name-only
CHANGELOG.md
dev/INTERNAL_DIFFERENCES.md
dev/MIGRATION_REPORT.md
dev/REFACTOR.md

$ git diff origin/v2.0 HEAD --name-only -- "*.py" "*.rs" "*.toml" "*.yaml" "*.yml" | wc -l
0

$ uv run --only-group lint ruff check
Found 28 errors.
[*] 28 fixable with the `--fix` option.

lint.yaml also failed on the two most recent pushes to v2.0, including 542c3c2 — the exact commit this branch is based on:

$ gh run list --workflow lint.yaml --branch v2.0 --limit 5
2026-08-03T21:09:16Z push 542c3c2 failure
2026-08-03T19:47:52Z push 505e7be failure

ruff --fix clears all 28, but that is a separate change and does not belong in a docs PR.

Two other checks are red for reasons this PR cannot reach either, both worth their own issues:

• windows (x64) — the wheel does not build: error[E0425]: cannot find function 'gethostname' in crate 'libc' at daisy-core/src/advertise.rs:145. libc::gethostname is Unix-only; on Windows it needs GetComputerNameExA/gethostname from the Winsock bindings, or #[cfg]. Introduced with the address-advertising work in 7128d9c, and publish.yaml builds windows (x64) wheels for release.
• test-wheel — ERROR: Could not find a version that satisfies the requirement tqdm>=4.65 (from daisy) (from versions: none): the smoke step installs with no index, so the runtime dependency cannot resolve. Its script is also stale against the change this CHANGELOG documents — it still passes worker_processes=False and num_workers=2, and Task(worker_processes=...) now raises TypeError.