feat: a prerequisite stage, and the EventLog corruption it uncovered

[sotashimozono]

Closes #46.

Stacked on #48. Merge that first.

The prerequisite stage

run! locks the KEY, so work shared between keys has nowhere to live but inside work_fn, where it has no protection at all: every worker that wants a setup not yet on disk builds it itself.

run_loop!(work_fn, vault, keys;
          prerequisite = Prerequisite(prep_fn, prep_vault, derived_keys))

The setup becomes its own key space and gets the same locking, resume and provenance as any other stage.

Measured, 8 concurrent processes

16 keys sharing 2 setups (8 keys per fibre), gated so the processes start together:

	setup builds
check-then-build inside work_fn	16
prerequisite stage	2

(With a 2-key fibre the same experiment gives 2 against 1: the duplication ceiling is fibre width, which is why the wide fixture is the one worth quoting.)

The correctness argument is the stronger one

work_fn's wall clock included the setup for one key in each fibre and excluded it for the other ~199. A cost claim built on that number depended on scheduling luck. With the setup in its own stage its cost is recorded in its own payload, and the dependent timings are clean.

It is a barrier, not a work loop

That is the whole difference from run_loop!, which stops after max_empty_rounds empty rounds. A round that finds every remaining key held by a sibling sleeps and goes again, because the dependent stage cannot start until the setup exists. Terminates on: all done; no progress and nothing held by a sibling; stop_flag; deadline.

If the prerequisite does not complete, the dependent stage does not start. Running it anyway would spend the allocation on keys whose setup is known to be missing, which is what Preflight already exists to prevent one layer up.

Not a DAG. SweepRunner does not know which dependent key needs which prerequisite key; that is resolved inside work_fn. This is "all of the prerequisite, then all of the dependents", and the docstring says so.

run_loop! now returns (; ran, rounds, done, stopped_by, prerequisite) instead of nothing.

EventLog corruption, found on the way

The :key_acquired event from #48 roughly doubled the event rate and turned a rare failure in test_run_keylock.jl into a frequent one. It is not a flake and it is not new:

4 EventLog objects on one path, 300 events each, 4 threads
  before: 947 of 1200 lines, 82 malformed
  after:  1200 of 1200,      0 malformed

test_run_keylock.jl, 10 runs each
  base branch (no key_acquired):  2/10 tore a line
  with key_acquired:              3/10
  with this fix:                  0/10

run! builds a fresh EventLog on every call, so four concurrent masters in one process hold four objects pointing at one file and four different ReentrantLocks. The documented "serialized through an internal ReentrantLock" was false in exactly the configuration the repo's own tests use, and events were being lost, not merely spliced.

Two fixes, both needed:

• the lock is now held per path, process-wide, so several EventLogs on one file share it;
• the write goes to an unbuffered append descriptor. open(path, "a") gives an IOStream, which flushes on its own boundaries, so write(io, line) was never the single syscall the O_APPEND guarantee is about. The docstring claimed it was.

The regression test covers both halves: threads within one process, and four separate processes appending to one file.

Verification

All 20 test files under test/, green. New: test_prerequisite.jl (33 assertions), test_eventlog_shared_path.jl (9).

The prerequisite tests carry their controls:

• a testset asserts the setup is built once per setup key; the next one asserts that without the prerequisite the same fixture does duplicate, so the first is not passing for having nothing to prevent;
• the barrier test holds one setup key with a live sibling lock that is never released and asserts the run waited (pre.waited >= 1, elapsed past the poll) and was ended by the deadline, rather than returning early the way run_loop! would.

Patch bump, 0.6.2 -> 0.6.3.

🤖 Generated with Claude Code

[github-actions]

📚 Docs preview: https://qatlashub.github.io/SweepRunner.jl/previews/PR49/

(updates on each push to this PR)

[sotashimozono]

Folded into #51.

The stack was one patch bump per pull request, each a single step above its own base, which is what version-check asks of a pull request. Merging them in sequence would have published a patch version to General for each one, including one whose content is test: Aqua. Collapsing the stack onto main ships it as one step instead.

Every commit from this branch is in #51 unchanged, so nothing here is lost; this body stays readable as the per-change account. The branch is kept.