Cubase-MCP-GAJ3T.MusicGen.R.../prompts/report_4.md

272 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

```
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.
```