MIDI 2.0 Gap Closure Tracker

Last Updated: 2025-12-16
Related Documents:

comprehensive-spec-audit-report.md - Full audit analysis
spec-audit.md - Page-level spec references
conformance-checklist.md - Implementation status
legacy/midi2-js-gap-plan.md - TypeScript gap plan

Status Legend

🔴 Not Started - Gap identified but no work begun
🟡 In Progress - Active development
🟢 Complete - Gap closed and validated
⏸️ Blocked - Waiting on external dependency

High Priority Gaps (Critical Path)

Gap 2.2.1: Property Exchange Subscription Lifecycle

Status: 🟢 Complete
Priority: High | Effort: 5-7 days | Target Sprint: 1

Spec Reference: M2-103-UM v1.2, Tables 43-47 (p.42-43)

Current State:

✅ Schema fields captured (MidiCiPropertyExchangeBody.subscriptionCommand)
✅ TS and Swift subscription managers implement start/partial/full/notify/end lifecycle with flow-control ACK/NAK, resource checks, chunk order enforcement, exponential backoff + retry-capped timeout (408), and tests
✅ Backoff/retransmit policy implemented at helper level; higher-level retry wiring remains optional

Acceptance Criteria:

Implementation Steps:

Design subscription state machine
Implement SubscriptionTracker class (Swift) / module (TS)
Add flow-control ACK/NAK message handlers
Implement chunk validation and retransmit
Add resource capability checking
Create test fixtures from M2-103-UM Tables 43-47
Update PropertyExchange.swift and pe-subscriptions.ts

Files to Modify:

Swift: Sources/MIDI2CI/PropertyExchange.swift
TypeScript: midi2.js/src/pe-subscriptions.ts
Tests: Add PropertyExchangeSubscriptionTests.swift and update pe-subscriptions.test.ts

Dependencies: None

Gap 2.2.3: Process Inquiry Runtime Validation

Status: 🟢 Complete
Priority: Medium | Effort: 1-2 days | Target Sprint: 2

Spec Reference: M2-101-UM v1.2, Table 40-42 (p.59-60)

Current State:

Device ID scope validation enforced in ProcessInquirySession.
Message Report replies clamp to supported filters and drop unsupported keys.
Tests cover capability inquiry, message report clamping, and invalid device IDs.

Acceptance Criteria:

Device ID scope validation (0x00–0x0F, 0x7E, 0x7F).
Message report filter intersection/min with supported capabilities.
Tests for inquiry/reply flow, clamping, and invalid device IDs.

Files Modified:

Swift: Sources/MIDI2CI/ProcessInquirySession.swift
Tests: Tests/MIDI2Tests/ProcessInquirySessionTests.swift

Dependencies: None

Gap 4.2.1: Function Block Descriptor Details

Status: 🟢 Complete
Priority: High | Effort: 4-5 days | Target Sprint: 1

Spec Reference: M2-104-UM v1.1.2, Figure 22 (p.40), Appendix I (p.122)

Current State:

✅ Typed FunctionBlockInfoNotification with direction/bandwidth/active/uiHints validation and reserved-bit checks; round-trip tests in StreamMappingTests.
✅ GroupTerminalBlocks encodes/decodes function block info; ranges enforced.
✅ UI hints captured (TS + Swift, schema bridge).
✅ Discovery/response flow covered by Function Block info encoding/decoding.
✅ Profile associations stored in negotiation layer (metadata map); demos update map on profile enable/disable; VRT-Protocol fixture added.

Acceptance Criteria:

Direction enum (.reserved, .input, .output, .bidirectional).
MIDI 1.0 bandwidth enum (.notMidi1, .unrestricted, .restrict31_25kbps, .reserved rejected).
Active flag + UI hints enforced.
Runtime validation of all field values and reserved bits.
Discovery/response flow implementation.
Tests: direction coverage, bandwidth rejection, reserved bits, round-trip.
Documentation cross-reference to Figure 22.

Implementation Steps:

Add Direction and Bandwidth enums
Extend FunctionBlockMessage bit field parsing
Add validation for reserved values
Implement discovery request/response handling
Create profile-FB association logic
Add comprehensive tests per Figure 22
Update schema documentation

Files to Modify:

Swift: Sources/MIDI2/Stream/FunctionBlockMessage.swift
Swift: Sources/MIDI2/Stream/FunctionBlockDiscovery.swift
TypeScript: Schema bridge for OpenAPI types
Tests: Tests/MIDI2Tests/StreamFunctionBlockDiscoveryTests.swift
Schema: midi2.full.closed.schema.json (add direction/bandwidth/active)

Dependencies: None

Gap 4.2.2: GTB Negotiation Semantics

Status: 🟢 Complete
Priority: High | Effort: 4-5 days | Target Sprint: 2

Spec Reference: M2-104-UM v1.1.2, Appendix I (p.122)

Current State:

✅ GTB structure defined (GroupTerminalBlocks.swift) with overlap/coverage validation and runtime enforcement helpers (Swift + TS)
✅ Spec-driven GTB context source documented (docs/gtb-context-source.md) with loaders (GtbDescriptor.load, loadGtbDescriptorFromJson) and sample config (docs/config/gtb.context.json)
✅ MT=0xF/0x0 reception restrictions enforced via GTB allowed-MT guards (Swift UMP/word guards; TS decoder/dispatch/raw-word guards)
✅ GTB-Function Block overlap policy documented (docs/gtb-overlap-policy.md); allow-overlap escape hatch supported in validators and negotiation sessions
✅ GTB protocol/ingestion scheme documented (docs/gtb-protocol-negotiation-scheme.md) with helper APIs (negotiateGtbContext, guardIngress/guardOutgoing)
✅ VRT-Protocol fixtures/tests for GTB overlap and MT blocking (docs/vrt-protocol/stream/gtb_overlap.json, gtb_block_mt.json, gtb_block_utility.json)
✅ Demo runtime (midi2device) loads GTB config when present and applies ingress/egress GTB guards

Acceptance Criteria:

Implementation Steps:

Document GTB-FB overlap rules from Appendix I
Add GTB validation against Function Block configuration
Implement message type reception restrictions
Add protocol negotiation state machine for GTB
Create test scenarios from Appendix I examples
Update runtime documentation

Files to Modify:

Swift: Sources/MIDI2/Stream/GroupTerminalBlocks.swift
Swift: Add Sources/MIDI2/Stream/GTBNegotiation.swift (new)
Tests: Tests/MIDI2Tests/GroupTerminalBlocksTests.swift
Docs: Add GTB negotiation guide (notes started)

Dependencies: Gap 4.2.1 (Function Block details)

Medium Priority Gaps (Sprint 2-4)

Gap 4.2.3: Stream Configuration Semantics

Status: 🟢 Complete
Priority: Medium | Effort: 3-4 days | Target Sprint: 2

Spec Reference: M2-104-UM v1.1.2, Figures 18/19 (p.37-38), Section 7.2.2.3 (p.45)

Current State:

✅ Protocol bits defined (0x01 MIDI 1.0, 0x02 MIDI 2.0)
✅ JR Tx/Rx flags in schema
✅ JR fallback + protocol switching with stateful negotiation (negotiateStreamConfig)
✅ Mismatch policy + shouldNotifyPeer surfaced for when to emit notifications (mismatch/protocol switch/first config/forced)
✅ Tests cover downgrade, JR fallback, repeated-request idempotence, and protocol switch notification policy
✅ Design doc: docs/stream-config-negotiation.md

Acceptance Criteria:

JR fallback when receiver doesn't support JR
Protocol switching (MIDI 1.0 ↔︎ MIDI 2.0)
Stream Config Notification sending on capability mismatch
Tests for negotiation failures and fallbacks
Documentation of negotiation flows

Implementation Steps:

Implement JR capability checking
Add JR fallback to non-timestamped mode
Implement protocol switching state machine
Add Stream Config Notification generation
Create negotiation test scenarios
Document negotiation patterns

Files to Modify:

Swift: Sources/MIDI2/Stream/StreamConfigurationMessage.swift
Swift: Add Sources/MIDI2/Stream/NegotiationSession.swift updates
Tests: Add negotiation test cases

Dependencies: None

Gap 8.2.3: Negative Test Coverage Expansion

Status: 🟡 In Progress
Priority: Medium | Effort: 4-5 days | Target Sprint: 3

Spec Reference: M2-104-UM v1.1.2 (reserved values throughout)

Current State:

✅ Some negative tests (Stream, SysEx8, MDS, profiles, PE compression)
✅ Initial reserved-value matrix seeded (docs/negative-test-matrix.md)
✅ Stream reserved-value cases added (Endpoint Info nfb > 0x20, stream config reserved bits, Function Block midi1Bandwidth=3, reserved mt bit) in Swift + TS
❌ Incomplete coverage across all decoders
❌ No comprehensive reserved value matrix

Acceptance Criteria:

Negative test matrix covering:
- All reserved opcodes per message type
- Out-of-range values for bounded fields
- Invalid bit patterns
- Malformed packet structures
Consistent error reporting Swift ↔︎ TypeScript
Fuzzing tests for randomized invalid inputs
Documentation of reserved value handling

Implementation Steps:

Create comprehensive reserved value matrix from specs (started)
Add negative tests for each message type (stream coverage started)
Implement consistent error types/messages
Add fuzzing test suite
Document reserved value handling strategy

Files to Modify:

Tests: Tests/MIDI2Tests/NegativeTests/ (new directory)
Tests: midi2.js/src/__tests__/negative.test.ts (new)
Tests: Tests/Fuzz/ - expand fuzzing

Dependencies: None

Gap 8.2.1: Visual Baseline (VRT-Protocol) Frames

Status: 🟡 In Progress
Priority: Medium | Effort: 3-4 days | Target Sprint: 3

Spec Reference: Internal testing methodology

Current State:

✅ Some VRT-Protocol baselines (JR, SysEx8 invalid cases)
❌ CI message baselines incomplete
❌ No automated diff tooling
🟡 Added VRT-Protocol README + generator script; stream/profiles/process-inquiry/property-exchange baselines exist

Acceptance Criteria:

VRT-Protocol baseline JSON files for:
- All MIDI-CI message types
- All Stream message variants
- Function Block messages
- Flex Data types
Automated schema regression checks in CI
Visual diff tooling for baseline comparisons
Documentation of VRT-Protocol methodology

Implementation Steps:

Create baseline JSON files in docs/vrt-protocol/
Implement schema diff tool
Add CI check for baseline regression
Document VRT-Protocol process

Files to Create:

docs/vrt-protocol/midici/*.json
docs/vrt-protocol/stream/*.json
docs/vrt-protocol/flex/*.json
Scripts/verify_vrt_protocol.py (new)

Dependencies: None

Gap 2.2.2: Profile Configuration Details

Status: 🟢 Complete
Priority: Medium | Effort: 2-3 days | Target Sprint: 4

Spec Reference: M2-102-U v1.1, Table 6 (p.15, 17)

Current State:

✅ Basic details replies (version, channel mask)
✅ PSD supported
✅ Added/removed helpers
✅ Negative tests expanded for details inquiries and target-less setOn handling
✅ Profile detail report handling includes PSD flag, unsupported profile handling, and last-details tracking

Acceptance Criteria:

Expanded profile detail report handling
Comprehensive tests for added/removed notifications
Profile configuration change tracking
Negative test cases for malformed messages
Documentation updates

Implementation Steps:

Review M2-102-U Table 6 requirements
Expand ProfileSession detail handling
Add profile change tracking
Create negative test suite
Update documentation

Files to Modify:

Swift: Sources/MIDI2CI/ProfileSession.swift
Tests: Tests/MIDI2Tests/ProfileSessionTests.swift

Dependencies: None

Gap 2.2.3: Process Inquiry Enhancement

Status: 🟢 Complete
Priority: Medium | Effort: 2-3 days | Target Sprint: 4

Spec Reference: M2-101-UM v1.2, Tables 40-42 (p.59-60)

Current State:

✅ Envelopes captured
✅ Session support with filter/messageDataControl validation (0/1/0x7F), device ID scope guard
✅ Unsupported/invalid filter values rejected (Swift + TS)
✅ TS/Swift negative coverage for malformed payloads

Acceptance Criteria:

Supported features bitmap validation (D0 bit = MIDI Message Report)
Device ID scope handling (0x00-0x0F, 0x7E, 0x7F)
Message data control value enforcement (0x00/0x01/0x7F)
Tests for system/channel/note message request bitmaps (negative filter values)
Documentation updates

Implementation Steps:

Implement features bitmap validation
Add device ID scope checking
Add message data control enforcement
Create test vectors from Tables 40-42
Update ProcessInquirySession

Files to Modify:

Swift: Sources/MIDI2CI/ProcessInquirySession.swift
Swift: Sources/MIDI2/MidiCiProcessInquiryBody.swift
Tests: Add ProcessInquiry tests

Dependencies: None

Gap 2.2.4: MUID Management

Status: 🟢 Complete
Priority: Medium | Effort: 2-3 days | Target Sprint: 4

Spec Reference: M2-101-UM v1.2 (MUID allocation/discovery)

Current State:

✅ MuidManager added in Swift (Sources/MIDI2CI/MuidManager.swift) and TypeScript (midi2.js/src/muid-manager.ts) with collision-avoidant allocation and reserved-value guarding.
✅ Conflict detection rotates local MUID on peer collision; peer map includes TTL-based expiry/cleanup and manual release.
✅ Tests cover allocation hints, conflict rotation, expiry/refresh flows (Swift MuidManagerTests, TS muid-manager.test.ts).

Acceptance Criteria:

MUID allocation/deallocation logic
MUID conflict detection and resolution
MUID timeout and cleanup
Tests for MUID lifecycle scenarios
Documentation of MUID management

Implementation Steps:

Implement MUID allocator
Add conflict detection
Add timeout tracking
Create lifecycle tests
Document MUID strategy

Files to Modify:

Swift: Sources/MIDI2CI/MuidManager.swift (new)
Tests: Add MUID tests

Dependencies: None

Gap 4.2.4: Endpoint Info Beyond Version/Max Groups

Status: 🟢 Complete
Priority: Medium | Effort: 2 days | Target Sprint: 2

Spec Reference: M2-104-UM v1.1.2, Figure 13 (p.33)

Current State:

✅ Schema has all fields defined
🟢 TypeScript runtime validation/tests added (reserved bit and NFB guard) 2025-12-13
🟢 Swift runtime validation/tests added 2025-12-13

Acceptance Criteria:

All Endpoint Info fields properly encoded/decoded
Reserved numberOfFunctionBlocks validation (0x21-0x7F) — TypeScript + Swift decode guard + tests
Comprehensive test vectors (Swift + cross-impl)
Documentation updates (tracker + test references)

Implementation Steps:

Add full field encoding/decoding
Add reserved value validation
Create test vectors
Update documentation

Files to Modify:

Swift: Sources/MIDI2/Stream/EndpointDiscoveryMessage.swift
Swift: Sources/MIDI2/Stream/EndpointInfoMessage.swift ✅
Swift Tests: Tests/MIDI2Tests/StreamMappingTests.swift ✅
TypeScript: midi2.js/src/ump.ts (decode validation) ✅
TypeScript Tests: midi2.js/src/__tests__/ump.test.ts ✅

Dependencies: None

Gap 8.2.2: Hardware Interop Tests

Status: 🔴 Not Started
Priority: Medium | Effort: High (ongoing) | Target Sprint: 5

Spec Reference: Real-world MIDI 2.0 devices

Current State:

❌ No hardware interop tests

Acceptance Criteria:

Test infrastructure for hardware communication
Reference MIDI 2.0 device test suite
MIDI-CI discovery/handshake validation
JR sync testing
Interop results documented

Implementation Steps:

Set up hardware test environment
Identify reference devices
Create interop test suite
Run validation tests
Document results and incompatibilities

Files to Create:

Tests/HardwareInterop/ (new directory)
docs/hardware-interop-results.md

Dependencies: Hardware access

Low Priority Gaps (Sprint 5+)

Gap 1.2.1: Reserved/Unsupported Status Handling

Status: 🟢 Complete
Priority: Medium | Effort: 2-3 days | Target Sprint: 5

Current State:

✅ Swift + TS decoders now reject reserved/unknown statuses for Flex, System, and Channel Voice instead of yielding raw events.
✅ Negative vectors added for flex unknown statuses, out-of-range channel voice values, and unsupported system statuses (Swift + TS).
✅ Reserved/value matrix updated (docs/negative-test-matrix.md) to capture enforcement strategy.

Acceptance Criteria:

Comprehensive reserved opcode table
Consistent error handling across decoders
Negative test vectors
Schema documentation of reserved values

Gap 5.2.2: Adapter Per-Note Controller Negotiation

Status: 🔴 Not Started
Priority: Medium | Effort: 2-3 days | Target Sprint: 5

Acceptance Criteria:

Per-note controller negotiation in WebAudio
Pitch-bend range negotiation/validation
Disposal safety tests for all adapters
Multi-group deterministic replay tests

Gap 5.2.1: Worker-Clock JR Projection

Status: 🔴 Not Started
Priority: Medium | Effort: 2-3 days | Target Sprint: 5

Acceptance Criteria:

Comprehensive worker-clock JR tests
Timestamp propagation validation
Clock drift compensation tests
Performance benchmarks

Gap 3.2.1: Flex Data Edge Cases

Status: 🟢 Complete
Priority: Low | Effort: 1-2 days | Target Sprint: 5

Current State:

✅ Runtime validation for tempo 16.16 range, time signature bounds, 12-byte text/ruby/lyric/chord/key payloads, and 10-byte metronome accent patterns (Swift + TS).
✅ Flex decoders reject reserved/unknown statuses and bad address bytes consistently across Swift/TS.
✅ Negative tests added in Swift (FlexValidationNegativeTests) and TS (flex-negative.test.ts, flex-reserved-negative.test.ts).

Acceptance Criteria:

Comprehensive Flex Data validation
Edge case tests (max lengths, invalid values)
Reserved opcode handling

Gap 1.2.2: UMP Format Extensions

Status: 🔴 Not Started
Priority: Low | Effort: 1 day | Target Sprint: 5

Acceptance Criteria:

Document supported utility opcodes
Placeholders for future types
Forward compatibility in schema

Gap 6.2.1: JR Interop Testing

Status: 🔴 Not Started
Priority: Low | Effort: Medium | Target Sprint: 5

Acceptance Criteria:

JR interop test suite
Clock/timestamp validation
Fallback behavior testing

Gap 7.2.1: Oversize SysEx Handling

Status: 🔴 Not Started
Priority: Low | Effort: 1 day | Target Sprint: 5

Acceptance Criteria:

Maximum SysEx size validation
Oversize error handling
Boundary fragmentation tests

Gap 9.2.1: Schema Documentation Completeness

Status: 🔴 Not Started
Priority: Low | Effort: Ongoing | Target Sprint: Ongoing

Acceptance Criteria:

All fields with descriptions
All fields with spec references
Examples for complex structures

Gap 9.2.2: Schema Regression CI

Status: 🔴 Not Started
Priority: Medium | Effort: 1-2 days | Target Sprint: 3

Acceptance Criteria:

CI check for OpenAPI codegen drift
Schema sync validation (JSON Schema ↔︎ OpenAPI)
Diff tool for schema changes

Gap 10.2.1: DoD Validation

Status: 🔴 Not Started
Priority: Low | Effort: 2-3 days | Target Sprint: 5

Acceptance Criteria:

Automated DoD checklist validator
Cross-reference tests/code with DoD
Updated DoD documents

Progress Dashboard

Overall Statistics

Total Gaps Identified: 21
High Priority: 0 (all closed)
Medium Priority: 10
Low Priority: 8

Status Summary

Note: Updated December 15, 2025 after comprehensive audit refresh.
🔴 Not Started: 8 (40%)
🟡 In Progress: 2 (10%)
🟢 Complete: 10 (50%)
⏸️ Blocked: 0 (0%)

Completed Gaps

Gap 2.2.1: PE Subscription Lifecycle 🟢
Gap 2.2.2: Profile Configuration Details 🟢
Gap 2.2.3: Process Inquiry Enhancement 🟢
Gap 2.2.4: MUID Management 🟢
Gap 4.2.1: Function Block Descriptor Details 🟢
Gap 4.2.2: GTB Negotiation Semantics 🟢
Gap 4.2.3: Stream Configuration Semantics 🟢
Gap 4.2.4: Endpoint Info Beyond Version/Max Groups 🟢
Gap 1.2.1: Reserved/Unsupported Status Handling 🟢
Gap 3.2.1: Flex Data Edge Cases 🟢

Sprint Allocation

Sprint 1 (Week 1-2): 2 gaps ✅ Complete
Sprint 2 (Week 3-4): 3 gaps ✅ Complete
Sprint 3 (Week 5-6): 3 gaps 🟡 In Progress
Sprint 4 (Week 7-8): 3 gaps ✅ Complete
Sprint 5+ (Week 9+): 10 gaps 🔴 Pending

Effort Distribution

1-2 days: 5 gaps (24%)
2-3 days: 7 gaps (33%)
3-5 days: 5 gaps (24%)
5-7 days: 1 gap (5%)
Ongoing: 3 gaps (14%)

Update Log

Date	Gap ID	Status Change	Notes
2025-12-15	All	📊 Audit	Comprehensive documentation audit; updated status counts to reflect actual implementation state
2025-12-14	2.2.x / 4.x	🟢 Progress	Schema bridge parity for MDS/stream (JS) + flex reserved/address guards; Swift Process Inquiry filter validation and PSD-aware profile details replies; tests green (npm check/test, swift test).
2025-12-13	8.2.3	🟡 Started	Added reserved-value matrix + initial stream negative tests (Swift/TS)
2025-12-14	2.2.3	🟢 Complete	Process Inquiry filter/messageDataControl validation; deviceId scope guard; TS+Swift negatives
2025-12-13	4.2.3	🟢 Complete	Stream config mismatch policy + notification rules; negotiation state machine + tests; doc
2025-12-13	4.2.1	🟢 Complete	Function Block info validation/uiHints, profile associations, discovery/name flow, VRT-Protocol fixtures
2025-12-13	4.2.1	🟡 Started	Added TS/Swift validation for Function Block Info (direction/bandwidth/active + reserved bits)
2025-12-13	4.2.4	🟢 Complete	Added Swift endpoint info validation + tests; TS validation already in place
2025-12-13	4.2.4	🟡 Started	Added TypeScript endpoint info reserved-bit validation and Vitest coverage
2025-12-13	All	🔴 Initial	Comprehensive audit completed

Maintained By: MIDI 2.0 Development Team
Review Frequency: Weekly during active sprints