272 lines
15 KiB
Markdown
272 lines
15 KiB
Markdown
```
|
||
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.
|
||
```
|