M5: wit-demo — the synthetic library the app is built and demoed against

[sepehrsadri]

What and why

Issue #18 depends on just demo-library so first-run, the timeline and the watcher are demoable on a machine with no real Logic library. That recipe called cargo run -p wit-cli -- demo-library — and wit-cli has never had a demo-library subcommand. The guard passed, then cargo errored. This builds the thing the recipe was always calling, and it is the prerequisite for developing the app against something other than someone's real 28 GB library.

New crate wit-demo writes a ~/Music-shaped tree:

Path	Shape
Logic/Coastline.logicx	10 saves, one alternative
Logic/Night Bus.logicx	two alternatives — Logic's own branching
GarageBand/Kitchen Jam.band	one save, no backups
Ableton/Coastline Project/Backup/	five autosaves in Live's own layout

21 versions, fully deterministic — no clock, no RNG, byte-identical run to run (pinned by a test).

It reads end to end through the real toolchain

$ just demo-library
  wrote 2 Logic project(s), 1 GarageBand project(s), 1 Ableton lineage(s) — 21 version(s) total
  these are synthetic fixtures for Wit's own readers — Logic and Live cannot open them

$ wit scan target/demo-library --data-dir target/demo-index
  found 3 Logic/GarageBand project(s), 1 Ableton lineage(s) — 21 new version(s) archived
    Coastline (logic): 10 version(s)
    Coastline (ableton): 5 version(s)
    Kitchen Jam (garageband): 1 version(s)
    Night Bus (logic): 5 version(s)
  # rescan: 0 new version(s) archived — idempotent

$ wit logic-report target/demo-library
  scanned 3 project(s), 4 alternative(s), 12 consecutive save pair(s)
  75.0% of save pairs show a structural change Wit can see (9 of 12)
  3 pair(s) (25.0%) are byte-different but structurally identical

$ wit diff-als "…101500].als" "…103012].als"
  no musical change detected (view / bookkeeping only)

$ wit diff-als "…111845].als" "…200133].als"
  2 semantic change(s)
    FX+     [Rhodes] added: AutoFilter
    CLIP~   [Rhodes] 'verse rhodes' muted

$ wit diff-als "…200133].als" "…204417].als"
  2 semantic change(s)
    TEMPO   120.0 -> 124.0 BPM
    SAMPLE~ 'rhodes take 3.wav' -> 'rhodes FINAL.wav'  (1 clip reference(s))

Three deliberate choices

The Logic chain is shaped to measured reality, not to look good. 3 of 9 pairs show nothing Wit can see — the 33% empty-verdict rate measured across 32 real projects (#15) — and all 3 are byte-different, §11's 28% case. A demo where every save had something to show would misrepresent the product, so a test pins the ratio and fails if it drifts.

GarageBand gets no backups, because the probe found real GarageBand keeps none. Inventing some would teach the wrong shape, and a test asserts their absence.

Its own crate, not wit-index. wit-index documents as an enforced-by-construction safety property that its only write API takes bytes, not a path, so no caller can hand it a project path even by mistake. A generator that writes a tree to a user-named path is exactly what that property excludes, so it lives here rather than eroding the claim. The guard rail moves with it: build_demo_library refuses any destination that is not empty — pointing it at a real library cannot destroy anything, verified both at the library level and through the binary.

The generated files carry real framing but only the fields Wit extracts. Logic and Live cannot open them, and the command says so on every run — a demo fixture must never be mistaken for a project.

One divergence this surfaced

tests/test_repo_hygiene.py's "no audio or DAW project file" check walks the filesystem; its CI mirror (check_no_binaries.sh) reads git ls-files. Generating a demo library into target/ — gitignored, uncommittable — turned the local suite red while CI stayed green, which is the wrong way round for a check whose whole value is failing in two seconds locally. It now skips root-level target/ the way it already skipped .git, with the reasoning in a comment. Verified it still fails on a stray tests/*.als.

Checklist

• Docs updated in this PR if behaviour changed
• No audio or project files committed (see .gitignore)
• Claims are labelled measured / cited / inferred

If this PR touches format parsing

This writes the two formats rather than parsing them, so both boxes apply in the mirror direction — every generated file is fed back through the real wit-logic / wit-als readers in tests, and the offsets it writes are the offsets those crates read:

• Unmodelled bytes still round-trip verbatim — generated payloads are zero-padded around the whitelisted fields; walk_records only returns Ok on an exact clean EOF, which every generated file reaches
• Malformed input is handled without crash or unbounded allocation — unchanged; no reader was touched

Gates

$ cargo test --workspace   149 passed, 0 failed   (was 126: +21 wit-demo, +2 CLI)
$ python3 -m pytest tests/ -q   293 passed, 13 skipped
$ cargo fmt --all --check / cargo clippy --workspace --all-targets --locked -- -D warnings   clean
$ cargo deny check licenses advisories   ok

Part of #18.

🤖 Generated with Claude Code