feedBack/specs/012-midi-input-domain/spec.md

Spec 012 — MIDI-Input Control-Plane Capability Domain

Status: active (control-plane slice) · Issues: #873 (impl), #880 (this spec) · Base: release/v0.3.0

Summary

midi-input is a core-owned provider-coordinator capability domain for MIDI device discovery, selection, and open/close session lifecycle — the MIDI analog of audio-input (spec 006). It gives every MIDI consumer in FeedBack (the input_setup onboarding wizard, the piano/keys and drums plugins, and — as a follow-up — note-detection's Web-MIDI provider) one device-access boundary: one permission prompt, one source list, one redaction boundary.

Motivation

Today each MIDI consumer calls navigator.requestMIDIAccess() privately (piano, drums, plugin-midi, note-detection's midi provider kind), so there is no shared source list, no single permission prompt, and no common redaction of device labels. The onboarding input-setup step (#874/#876/#877) needs a single governed surface to pick and verify a MIDI device per instrument.

Why not reuse audio-input

audio-input's source/source.open contract is audio-frame-centric: channelSummary/channelCount/channelShape, requiredChannelShape, and redaction keyed to audio handles/buffers/samples. MIDI carries discrete messages and has no channel shape. Folding MIDI in would overload the audio contract and its redaction boundary. A sibling domain keeps both contracts clean and lets each evolve independently — the same reasoning that made audio-input and audio-monitoring siblings rather than one domain.

Why core-owned (not plugin-owned)

An input control plane outlives any one feature; audio-input is core.audio.session-owned, not owned by a feature plugin. If input_setup owned midi-input, the domain's lifetime would be coupled to the wizard, and migrating ownership later (every consumer, persistence key, diagnostics schema references the owner) is costly. The domain is core.midi-input.

Contract

• Owner: core.midi-input, kind provider-coordinator, safety sensitive.
• Public commands: inspect, list-sources, discover, select-source, open-source, close-source.
• Provider operations: source.enumerate, source.describe, source.open, source.close.
• Events: provider-registered, provider-unregistered, availability-changed, sources-changed, source-selected, source-opened, source-closed.

Sources & identity

Providers register source summaries with providerId, a stable sourceId, a derived redaction-safe logicalSourceKey (providerId::sourceId), kind: "midi", a label, and availability. Persistence and diagnostics use the logicalSourceKey, never the human device label.

Permission model (Web-MIDI nuance)

requestMIDIAccess() gates the whole input list, so discover is the permission boundary (not open-source, as it is for audio). inspect / list-sources / select-source are prompt-free and never request access. discover records denied / unavailable outcomes; open-source attaches a shared listener session to an already-discovered source and never re-prompts.

Sessions

One shared open session per source across requesters (refcounted); the provider receives source.close only after the last requester releases. Live MIDI message delivery (for the "play a note / hit a pad" calibration check) is exposed to in-page consumers via the public window.feedBack.midiInput session handle only — never as raw capability events or in diagnostics.

Persistence & redaction

Selected source persists under feedBack.midiInput.selectedLogicalSourceKey. Diagnostics (feedBack.midi_input.diagnostics.v1) carry provider ids, source ids/keys/kinds/availability, the selected key, and open-session keys; device labels are redacted and no raw MIDI messages are ever included.

Split from midi-control

The reserved midi-control domain is narrowed to control mappings only (CC/pitchbend/note → action routing) and will consume midi-input for device access. This spec carves out the device control plane so midi-control can stay mappings-only (#882).

Consumers (separate issues)

• input_setup onboarding wizard — keys/drums device pick + verify (#876/#877).
• piano / drums plugins — consume midi-input instead of private requestMIDIAccess() (via the sub-flow issues; legacy retired through bridges).
• note-detection's Web-MIDI provider migrates onto midi-input (#881).

Acceptance

• Owner registers; appears in the Capability Inspector with the commands above.
• discover is the only command that triggers requestMIDIAccess(); inspect/list-sources/select-source never prompt.
• Selection persists across reload by logicalSourceKey.
• Diagnostics contain no device labels or raw MIDI messages.
• A consumer can discover → select-source → open-source → receive live note-on for the calibration check → close-source (session refcount releases).

Out of scope (follow-ups)

• midi-control mapping/routing domain (#882).
• note-detection provider migration onto midi-input (#881).
• Retiring per-plugin requestMIDIAccess() in piano/drums via compatibility bridges (tracked with the sub-flow issues).