``` Step 4 report — exact event-plan MIDI writer and saved-content validator Date: 2026-10-19 Result: PASS. Step 4 acceptance is verified; no implementation blocker remains. SCOPE AND PRESERVED WORK Read the approved plan, reports 1–3, authoritative Score/EventPlan/event/error models, existing test configuration, and installed Mido/MIDIUtil APIs/source before implementation. Independently verified the accepted contract/import baseline rather than treating the prior reports as test execution evidence. Created: - src\riff_groove_builder\midi.py - tests\unit\test_midi.py - tests\integration\test_midi_files.py - prompts\report_4.md Updated: - README.md - docs\architecture.md No schema/model/error/manifest changes were needed. Existing untracked work, prior prompts/reports, package initializer, server/CLI, and earlier tests were preserved. No commits, delegation, later prompts, production instrument maps, native codecs, description/composition, or MCP generation wiring were added. No dependencies were installed or restored. API AND SERIALIZATION DECISIONS Public typed APIs: - beats_to_ticks(Fraction | RationalBeat | int, ppq=960) -> int - bar_ticks(TimeSignature, bars=1, ppq=960) -> int - quarter_tempo(tempo_bpm: float) -> int - validate_event_plan(EventPlan) -> None - write_midi(path: Path, plan: EventPlan) -> Path - validate_midi_file(path: Path, plan: EventPlan) -> None Mido is the sole production SMF serializer/parser. MIDIUtil is test-only. Strict Pydantic models are revalidated through the whole mutable graph before MIDI-specific checks, so mutated lists/fields and unchecked model updates do not bypass event, payload, timeline, uniqueness, or event-budget validation. Named failures reuse SerializationError, OutputExistsError, and OutputIOError. Details contain fixed safe reasons and selected safe numeric/role/part context, not raw exceptions, descriptions, private paths, or tracebacks. Quarter-note timing stays exact. Floats/booleans/string beat positions and off-grid fractions are rejected. Bar duration is numerator * 4 / denominator quarter notes, multiplied by bars and PPQ. Relative logical-note offsets and durations must be representable; a nonzero Score.start is not extra pre-roll. The writer preserves compiled absolute ticks rather than compiling the score. PPQ defaults to 960 and must be an integer in 1–32767 (no SMPTE division). Every delta is an integer in 0–0x0FFFFFFF. Because the conductor has no invented filler events, its EOT delta spans the plan, so end_tick is also bounded by 0x0FFFFFFF. Oversize gaps fail explicitly instead of being split or rounded. The existing 100,000 scheduled-event budget excludes bounded SMF metadata. Tests accept 99,999 and 100,000 events and reject 100,001. Tempo means quarter-note BPM regardless of meter denominator. The exact decimal-rational reciprocal is rounded to nearest microseconds/quarter, ties to even, within 1–0xFFFFFF. Intent still enforces its existing 20–300 BPM range. Examples verified: 120 -> 500000; 120.125 -> 499480; 137.5 -> 436364; 102.4 -> 585938 and 61.44 -> 976562 exercise opposite half-even ties. SMF type 1 contains Conductor followed by selected part tracks in resolved order. Names are Conductor/Lead/Bass/Drums, without plugin identity claims. Conductor tempo and meter are at zero. Supplied notes, keyswitches, velocities, and CC payloads remain in their part tracks. Exactly one EOT per track uses the shared end_tick, including empty parts and control-release tails. No programs, GM drum channel/map, real switches, or control lead times are invented. Common pre-roll, musical span, and release tails remain unchanged; musical onsets at/after musical end and out-of-span musical releases fail. ORDERING, NOTE PAIRING, AND CHANNEL POLICY Events are stable-sorted only by (tick, priority, sequence). Input lists are not mutated, and valid explicit control causality is not replaced by generic priority/pitch sorting. Integer absolute ticks become deltas exactly once when constructing Mido tracks. Active notes are keyed by channel/note within a part, with musical/keyswitch roles retained for validation and diagnostics. Every onset needs a matching positive-duration same-role release. Orphans, dangling notes, role-mismatched releases, and same-channel/same-pitch overlaps are rejected. That includes musical/keyswitch collisions: no ambiguous voice allocation is guessed. A boundary retrigger must release first in the supplied ordering. A pitch can change role after release. Different pitches on one part channel are valid polyphony; the same pitch on separate channels is independent. Every used channel belongs to one part for the entire plan, including CC-only and keyswitch usage. Distinct parts cannot share it even at different times. A part can own multiple otherwise disjoint channels; empty parts reserve none. No zero-based channel 9/default drum-channel assumption is made. REAL SAVED-FILE VALIDATION AND FAILURES The writer serializes and expected-content-validates in memory, exclusively creates only the requested path with xb, closes it, reads the actual saved bytes, and parses them with Mido. It compares header/type/PPQ/track count, names/order, conductor tempo/meter, every absolute message tick and payload, channels, note/CC/velocity data, event ordering, and shared EOT against expected content. Exact equality to the already-pair-validated plan also verifies the saved note pairs. Merely opening a readable MIDI file is not success. Truncation, corrupt chunks/header, trailing data, and readable wrong content all fail. An integration fault actually modifies a just-saved file on disk; the read-back mismatch is detected and the owned file is removed. Pre-existing files/directories are rejected; xb also protects a collision after the precheck. Parent directories are not created. Expected IO/library failures have narrow catches; unexpected programming errors propagate and still trigger owned-file cleanup. No MIDI-shaped success/fallback hides errors. Cleanup checks device/inode identity and never removes a replacement file. If deletion itself is denied or ownership changes, a named explicit IO error is returned rather than a success or silent cleanup failure. The standalone validator never deletes its input, including deliberately corrupt files. The API acts only on the supplied Path. Output-root confinement, adversarial link/race protection, fsync/crash durability, directory publication, requested format/fallback policy, and MCP integration are not claimed. Step 9 must stage all artifacts and publish only after every writer succeeds. INDEPENDENT MIDIUTIL EVIDENCE Four real-disk comparisons pass: - 4/4, 120 BPM - 3/4, 137.5 BPM - 6/8, 120.125 BPM - 7/8, 137.5 BPM Each constructs a synthetic three-part Score/EventPlan, logical score origin 2 beats, 240-tick common pre-roll, triplet durations, same-pitch retrigger, keyswitches, CC selections/resets, and a 120-tick shared tail. Resolved order is Bass/Drums/Lead, using channels 5/12/2. All pitches, voices, controllers, switches, and channels are arbitrary test-local values, not production maps. An independent MIDIUtil builder uses explicit addNote(start, duration, volume) and addControllerEvent calls, not production sorting/timing/render helpers or iteration over production EventPlan events. Mido parses both saved files. Normalized note/control events compare exactly by absolute tick, event kind, channel, pitch/controller, and onset/release velocity or CC value. Explicit expected event lists independently check all those values and durations. Verified and explicitly accounted library conventions: - MIDIUtil type 1 inserts a conductor ahead of its three user tracks. - Its time-signature API takes the denominator exponent. - Its note-off velocity copies the onset velocity. The independent fixture's supplied release velocities match this convention; comparison does not discard release velocities. Production separately preserves arbitrary legal releases, including zero, 17, and 127; no MIDIUtil convention is imposed. - Its tempo truncates: 137.5 -> 436363 and 120.125 -> 499479. Production correctly rounds to 436364 and 499480. Tempo is tested separately, not falsely declared byte/payload-equal across libraries. - Reference EOTs are local last-event positions; production uses the common full tail. Both conventions and meter/conductor data are separately asserted. Only these metadata conventions are excluded from note/control equality. - Duplicate removal, deinterleaving, and origin adjustment are disabled in the reference so intended events and pre-roll are not silently transformed. Repeated identical production plans, and plans with reversed input event lists, produce identical bytes with Mido 1.3.3. Cross-library byte equality and untested dependency-version byte reproducibility are not claimed. EXACT VALIDATION COMMANDS AND OUTCOMES Environment: Windows AMD64; repository .venv; CPython 3.13.13. Verified versions: Mido 1.3.3; MIDIUtil 1.2.1; Pydantic 2.14.1; pytest 9.1.1; Ruff 0.17.1; mypy 2.4.0; MCP 1.30.0. Other Python versions/OSes/dependency versions were not executed. All commands ran at the repository root. Scratch variables: $scratch = New-Item -ItemType Directory -Force '.test-artifacts\scratch' $env:TEMP = $scratch.FullName $env:TMP = $scratch.FullName $env:TMPDIR = $scratch.FullName $env:PIP_NO_INDEX = '1' Independent pre-implementation accepted-contract/import baseline: & '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_schemas.py tests\unit\test_errors.py tests\integration\test_contracts.py tests\unit\test_package.py -q PASS: 325 passed in 1.43s; 0 failed, 0 skipped. Final focused new tests: & '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_midi.py tests\integration\test_midi_files.py -q --tb=short PASS: 135 passed in 2.27s; 0 failed, 0 skipped. Breakdown: 110 unit cases and 25 integration cases. Final complete suite: & '.\.venv\Scripts\python.exe' -m pytest -q --tb=short PASS: 515 passed in 21.73s; 0 failed, 0 skipped; no warnings reported. Includes all 135 new MIDI cases and every 380 existing regression case: strict schemas/errors/JSON contracts, import/package smoke, real stdio protocol/unfinished-handler tests, and both offline distribution build/install checks. Those existing distribution tests build sdist/wheel with no isolation, install an isolated wheel venv offline, and verify package imports outside the checkout; they do not certify plugin compatibility or installed-wheel MIDI. & '.\.venv\Scripts\python.exe' -m ruff check . PASS: All checks passed! & '.\.venv\Scripts\python.exe' -m ruff format --check . PASS: 28 files already formatted. & '.\.venv\Scripts\python.exe' -m mypy PASS: Success: no issues found in 15 source files. & '.\.venv\Scripts\python.exe' -m pip check PASS: No broken requirements found. git --no-pager diff --check PASS: no tracked-diff whitespace errors. Work remains untracked, so full Ruff checks additionally cover authored Python rather than relying on git diff. Editor runTests was attempted with both absolute new test paths and returned "No tests found in the files." This is not a pass or skip. The authorized verified pytest CLI fallback above supplied actual execution evidence. Editor problems queries reported no errors in all three new Python files. Strict mypy/lint settings were not relaxed. Only narrow import-untyped ignores cover the installed Mido/MIDIUtil libraries, which do not provide typing stubs. DEVELOPMENT ISSUES AND CORRECTIONS Initial lint found three overlong lines; formatting fixed them. Initial mypy found five variable/literal inference diagnostics; distinct score/event-track variables and explicit Part list typing fixed them without broad suppression. The first focused run had 118 passed and 5 failed: - Windows xb on an existing directory raised PermissionError rather than FileExistsError. An existence precheck now reports OutputExistsError, with exclusive creation retained and a separate collision-race regression. - Four independent comparisons exposed the actual MIDIUtil release-velocity convention. Corrected the synthetic equivalent input/expected events to include those velocities rather than weakening normalization or ignoring payload differences. The five previously failing cases then passed. Added boundary coverage for rational helper mutation, half-even tempo ties, huge/unrepresentable tempo, PPQ endpoints on disk, MIDI payload endpoints, keyswitch release tails, invalid paths, short writes, and collision races. The final focused and complete runs above pass; no known step-caused failure or unresolved Step 4 implementation issue remains. CLEANUP, PERSISTENCE, AND READINESS GATES All new MIDI files use unique repository-local .test-artifacts\midi-unit-* and midi-files-* workspaces, removed by fixture finally cleanup even on failed tests. No licensed/checked-in binary fixtures or external temporary workspaces were authored. Injected cleanup-denial residue is explicitly removed after the test restores normal filesystem operations. Pre-existing ignored scratch, caches, and build products were preserved. Final inspection: remaining owned MIDI/distribution/stdio workspaces = 0; remaining matching repository test child processes = 0. No background services were started. Prompt inventory stops at step_4.md; no later prompt exists. Step 4 acceptance gate: SATISFIED — exact deterministic type 1 SMF from explicit plans, tested safe ordering/pairing/channels, actual saved-content comparison, independent MIDIUtil event evidence, explicit failure/cleanup behavior, and all regressions/lint/format/types passing. Implementation, tests, docs, and this report persist in the requested repository. Can Step 5 start? YES for reviewed profile/compiler mechanics and synthetic tests after Step 4 acceptance; this report does not authorize invented maps. Is Step 5's real production-mapping acceptance gate currently satisfiable? NO. Exact Eclips/Ray product identities/versions, SD3 version/library/preset/map, lawful evidence for playable ranges, channels, keyswitch/CC semantics, velocity layers, and actual target behavior remain unverified. Synthetic compiler tests cannot close that gate; verified vendor/user evidence is still required. Native gates remain separately OPEN: AGP/SDP layouts and content semantics, lawful controlled fixtures/redistribution permission or local-only procedures, and actual target-plugin/Cubase import/load/save/reload acceptance are missing. No manual application/client acceptance ran, and none is represented as an automated pass or skip. Renamed MIDI is not native support. The stdio registry remains empty and generate_music remains the reviewed development-only unfinished handler. This is Step 4 readiness, not a functioning text-to-music server, instrument-compatible generator, or full-project release. ```