# Instrument profile and event-intention contract ## Status and evidence boundary Correction iteration 4 now admits **five Documented default capabilities**: AGLP/AGM/AGT/AME Lead Sustain/PalmMute, and ABJ Bass **Sustain only**. AMR and SD3 remain `mapping_unavailable`; ABJ PalmMute explicitly fails `unsupported_articulation`, not a guessed PM/Dead Note velocity transform. Published manuals plus vendor demo MIDI provide genuine numeric anchors; switch timing/routing are disclosed writer policies, not vendor-certified limits. `Documented` means source-backed defaults, **not installed-plugin acceptance**. `Verified` remains the application-verified stage; zero shipped profiles have that status. `Unverified` and `Synthetic` are rejected in production. Full requested-product/application readiness remains **false / BLOCKED**. See [the compatibility inventory](format-compatibility.md). ## Declared instrument catalog (correction iteration 2) The owner requested six Ample targets, plus the existing SD3 target. Immutable Core `InstrumentDefinition` contains only `id`, string `vendor`, `productCode`, `displayName`, the existing `role`, and `documentationUrl`. It deliberately has no fabricated version, playable range, controls or native capabilities. | ID | Vendor | Code | Display name | Role | Official documentation | | --- | --- | --- | --- | --- | --- | | `ample-abj` | Ample Sound | ABJ | Ample Bass J | Bass | [ABJ manual](https://www.amplesound.net/en/Main_Panel_Manual-ABJ.pdf) | | `ample-aglp` | Ample Sound | AGLP | Ample Guitar LP | Lead | [AGLP manual](https://www.amplesound.net/en/Main_Panel_Manual-AGLP.pdf) | | `ample-agm` | Ample Sound | AGM | Ample Guitar M | Lead | [AGM manual](https://www.amplesound.net/en/Main_Panel_Manual-AGM.pdf) | | `ample-agt` | Ample Sound | AGT | Ample Guitar T | Lead | [AGT manual](https://www.amplesound.net/en/Main_Panel_Manual-AGT.pdf) | | `ample-ame` | Ample Sound | AME | Ample Metal Eclipse | Lead | [AME manual](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf) | | `ample-amr` | Ample Sound | AMR | Ample Metal Ray5 | Bass | [AMR manual](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf) | | `toontrack-sd3` | Toontrack | SD3 | Superior Drummer 3 | Drums | [SD3 manual](https://www.toontrack.com/manual/superior-drummer-3/) | Names/manual URLs were confirmed through the official rendered website in the approved correction. Identities are not proof of installation or mapping. The owner's folder screenshot establishes neither versions, directory paths nor maps. Acoustic guitars occupy the existing Lead/guitar slot; no new track roles, extra slots, strumming patterns or per-product articulation assumptions. Generation `InstrumentCatalog.LoadEmbedded()` reads `Instruments\instruments.json` independently of cwd, ordered by ordinal ID. `Find(id)` uses exact IDs and returns null when unknown; `ForRole(role)` returns an immutable filtered list, rejecting undefined roles. IDs/codes must contain only nonempty ASCII letters/digits, dash/underscore/dot. Vendor/display name must be nonempty, trimmed and free of control characters. Documentation URLs must be absolute HTTP(S), without credentials or whitespace. Duplicate IDs and duplicate vendor/code or vendor/name identities are invalid; versions belong in profiles, not duplicate definitions. The profile catalog's immutable joined `Instruments` entries expose `Instrument`, matching versioned `Profiles`, and derived `Availability`: - `mapping_unavailable`: no admitted Documented/Verified mapping exists. - `profile_available`: at least one admitted Documented/Verified mapping exists. Neither status asserts native writer support, installed plugins, supported extensions, or application/Cubase acceptance. All four guitars and Sustain-only ABJ are available under the scope below; AMR and SD3 remain unavailable. Step 8 exposes `list_instrument_profiles` and `generate_project` with this same bounded evidence scope and explicit selection; native writers and application verification remain absent. ### Adding another instrument as data 1. Add a JSON definition with a unique ID and identity to `Generation\Instruments\instruments.json`, with a real documentation URL and one existing role. Vendor is data, not a product/vendor enum. 2. After authorized documentation review or actual application verification, add profiles to `Generation\Profiles\instrument-profiles.json`. Each needs a unique profile ID, required `instrumentId` referencing the definition, matching role and exact `productName == displayName`, honest product-version scope, independent mapping revision, evidence and all mapping fields below. Documented profiles also require explicit compatibility notes. Multiple versions share an instrument ID, not a profile ID. Do not fill mapping gaps with test fixture numbers. 3. Run catalog/profile/planner tests, rebuild and publish: resources are embedded. There are no runtime directories, hot reload, VST scanning/loading, reflection plugins or external services. Existing mechanisms need no subclass, product switch or engine change. New mechanisms still require separately reviewed work. Test-only JSON fixtures add extra vendor-neutral targets and two versions for one target; selection and the unchanged planner consume both. Their invented `Verified` evidence exercises admission validation only, not application truth. They live solely in the test assembly. Production still rejects `Synthetic` and `Unverified` profiles, even when every other field/binding is valid. Future native writers remain format-based, not per-instrument hierarchies; no writer implementation or unverified shared Ample native format is implied. ## Additional evidenced capabilities (correction iteration 4, 2026-10-20) All five IDs end in `-documented-defaults-2026-10-20`, with instrument prefixes `ample-aglp`, `ample-agm`, `ample-agt`, `ample-ame` and `ample-abj`. No role default is authorized; each selected role requires an explicit ID. | New profile prefix | Articulations | Absolute switch/range | Musical velocities | Route | | --- | --- | --- | --- | --- | | `ample-agm` | Sustain, PalmMute | 24/26; 40-84 | Sustain 1-126, PM 1-127 | Lead channel 0 | | `ample-agt` | Sustain, PalmMute | 24/26; 40-84 | Sustain 1-126, PM 1-127 | Lead channel 0 | | `ample-abj` | **Sustain only** | 24; 35-76 | Sustain 1-125; 126-127 are excluded accents | Bass channel 1 | These extend, not alter, the AGLP/AME numeric rules and source records below. They share unknown-initial-articulation initialization and the explicit velocity-100/120-tick advance/30-tick pulse writer policy. Source/demo timing is **not** a certified pulse minimum or latency measurement. Bass channel 1 (display channel 2) is a project routing policy, not the demo's channel 0. Default tuning/mapping/velocity thresholds, instrument mode, MIDI Guitar mode off and an isolated idle receiver remain required. Full installed/application acceptance is still unverified. ### AGM: direct numeric switches The rendered [official download page](https://www.amplesound.net/en/download.asp) publicly lists both AGM projects: - [AGM-Rylynn.zip](https://www.amplesound.net/dl0822/ds/AGM-Rylynn.zip), HTTP Last-Modified 2019-06-11 17:57:25 GMT, SHA256 `e88c40ce4e67fde7b692b7f1cd5c4d057d7cd2a50e21d71114379b55d1fabd6f`. Entry `AGM-Rylynn/AGM3-Rylynn.mid`, 480 PPQ, zero-based track 1 "G1", channel 0: note 24/velocity 80 on 32215/off 32335. - [AGM-Dear_Ben.zip](https://www.amplesound.net/dl0822/ds/AGM-Dear_Ben.zip), HTTP Last-Modified 2019-11-24 16:38:43 GMT, SHA256 `bb6dd773b5f998a1d0efa80ebc77d6661922e49f137f74a685000792ed618fe5`. Entry `AGM-Dear Ben/AGM-Dear Ben Tempo 74.mid`, 480 PPQ, track 1 "AGM ARP", channel 0: note 26/velocity 80 on 28798/off 28858; note 24/velocity 80 on 30238/off 30298. Together with AGM manual pp.6-7 §§2.2.1-2.2.4 (revision/hash below), these anchor C0=24, D0=26, E1-C5=40-84; Sustain 1-126 excludes Pop at 127. PM musical velocity 1-127 controls mute depth without a guessed transformation. ### ABJ: vendor-listed shared source, deliberately Sustain only The official download row explicitly lists products **ABJ ABP** for [AB-Articulations.zip](https://www.amplesound.net/dl0822/ds/AB-Articulations.zip). HTTP Last-Modified 2019-06-11 17:32:45 GMT, SHA256 `c3efc1dc787c59a00be7405687488317efaf952822aededf54b9e19f4e145cb7`. Entry `AB-Articulations/4.2 Articulations & Poly Legato.mid`, 480 PPQ, track 1 is named **ABP**, channel 0: note 24/velocity 90 on 3720/off 4080; musical note 40/velocity 90 on 3840. This is vendor-listed shared applicability, **not** an independently ABJ-named performance or an inferred AMR mapping. ABJ manual pp.6-7 §§2.2.1-2.2.4 documents C0, B0-E4 and Sustain 1-125; the numeric anchor yields switch 24/range 35-76. The dedicated D0 PalmMute/Dead Note split still lacks its numeric threshold. That blocks **PM**, not an otherwise supported Sustain-only capability. Discovery advertises only Sustain; requested ABJ PM fails explicitly with no file/partial arrangement. No fixed velocity, Sustain fallback or PM rule is invented. AMR does not inherit this ABJ/ABP source. ### AGT: confirmed named tab-play anchor, not a direct articulation performance The concrete lead was confirmed in the rendered official [Tab Player documentation](https://www.amplesound.net/en/tutorial-b.asp), §6.3 **Tab Play Toggle**: MIDI note **A6** controls tab play (high velocity on, low velocity off). Retrieved 2026-10-20; no HTTP Last-Modified header; HTML SHA256 `542ae25caec1dfea772fbe9f5cc80be0c12ad3104f057e654410226aa1e69e92`. This is the vendor's historical applicable Tab Player documentation, not a note name supplied by our MIDI library or an assumed octave convention. The official download row identifies "Tab Project - Wish You Were Here", products **AGT AGM**, linking [AGT-Wish_You_Were_Here.zip](https://www.amplesound.net/dl0822/ds/AGT-Wish_You_Were_Here.zip). HTTP Last-Modified 2019-06-11 18:04:59 GMT, SHA256 `82a9b42109519d20d9340c6c6cdb972a66663482df483fd0bf5034b84b5d9262`. The exact entry is `AGT-Wish_You_Were_Here/AGT3-Wish You Were Here Tempo 62.mid` (underscores in the directory), 480 PPQ. Tracks 1 "Solo" and 2 "Strum" each contain only note 105/velocity 80, channel 0, on 3840/off 4320. Matching that tab-play control to the documented named A6 establishes `C0 = 105 - (6*12 + 9) = 24`, hence D0=26 and E1-C5=40-84 from the reviewed AGT main-panel table. This is **not** a direct Sustain/PM performance. Historical source and non-versioned current main-panel revisions are recorded separately from an unknown installed release. The generated profile does not trigger Tab Player or emit note 105. All four ZIP MIDI streams were re-read with pinned DryWetMIDI 8.0.3; archives, MIDI, manuals and other vendor entries were not retained. No helper package, product installation, native-file inspection or access-control bypass was needed. AMR has no public demo among the nine inspected official rows; no invented URL, cross-bass substitution or open-ended search was attempted. SD3 stays unavailable. Built and refreshed published RPC tests exercise every Lead with ABJ, shared lead-in, separate channels/tracks, exact notes/controls and one fallback artifact. ## Documentation-backed defaults (correction iteration 3, 2026-10-20) This initial AGLP/AME source record is retained. The newly resolved AGM/AGT/ABJ anchors above supersede the original inventory's missing-anchor conclusions. ### Published numeric facts and admitted subset | Profile ID | Source mapping | Absolute pitches | Musical velocity constraints | | --- | --- | --- | --- | | `ample-aglp-documented-defaults-2026-10-20` | AGLP manual PDF pp.6-7, §§2.2.1, 2.2.3, 2.2.5 | Sustain C0 = 24, PM D0 = 26; E1-D5 = 40-86 | Sustain 1-126 (127 is Pop/Pinch Harmonic depending on settings); PM 1-127, lower velocity increases mute depth | | `ample-ame-documented-defaults-2026-10-20` | AME manual PDF pp.6-7, §§2.2.1-2.2.4 | Sustain C0 = 24, PM D0 = 26; C1-C5 = 36-84 | Sustain 64-126 only (1-15 full mute, 16-31 three-quarter, 32-63 half; 127 Pop/Pinch Harmonic); PM 1-127, lower velocity increases mute depth | Neither conversion starts with an assumed octave convention. The official [download page](https://www.amplesound.net/en/download.asp), inspected rendered, links these vendor-authored demo archives (read in memory, not redistributed): - [AGLP-Prison_Break.zip](https://www.amplesound.net/dl0822/ds/AGLP-Prison_Break.zip): HTTP Last-Modified 2019-11-24 16:33:18 GMT; SHA256 `738956bced4e78a00ab755646d34108f9e25c5346ef79b96a5c1664c876f5e5f`. `AGLP-Prison Break/AGLP-Prison Break-Tempo100.mid`, 480 PPQ, zero-based track 1: switch 24, velocity 100, on tick 3837/off 3957; track 3: switch 26, velocity 100, on 34438/off 34558. These are the actual numeric C0/D0 anchors for the manual's switch labels. - [AME-Eclipse.zip](https://www.amplesound.net/dl0822/ds/AME-Eclipse.zip): HTTP Last-Modified 2019-11-24 17:03:34 GMT; SHA256 `e448d85f9ff80692f625f23ef6ea4dd0b14367b9f92412adbb76aa6e4a987f66`. `AME-Eclipse/AME-Eclipse-Tempo130.mid`, 480 PPQ, zero-based track 4: switch 24, velocity 100, on 3720/off 3840, musical C1 pitch 36 at 3840. C0=24 anchors the manual's D0 two semitones above (26) and C1-C5 (36-84). Its `1 Channel` variant also contains switch 24. Existing pinned DryWetMIDI 8.0.3 read the demo streams; no parallel MIDI parser, copied demo, sample library or native content was retained. The public [third-party Eclipse map](https://github.com/zaibuyidao/ReaScripts/blob/98e88777ff4cf2e478d6bc85d35349f62acc7e41/Various/Articulation%20Map/banks/70-96%20Ample%20Metal%20Eclipse%20%28%E9%87%91%E5%B1%9E%E5%90%89%E4%BB%96%29.reabank) (blob `ea878807ac429bd7294b9f8a8612a9261feacb4f`) corroborates 24/26 only. Its implementation and velocity interpretations are not copied or substituted for vendor evidence. The public Reaticulate Rickenbacker bank also uses 24/26, but a different product does not establish the missing targets' numeric anchors. ### Source revisions and remaining gaps Retrieved 2026-10-20 from each catalog URL. Manuals are **non-versioned**; HTTP timestamps/hashes identify source revisions, not installed product versions. `productVersion` explicitly says documented defaults/installed version unknown; `mappingVersion` is our `published-defaults-2026-10-20.1` data revision. | Manual | HTTP Last-Modified (GMT) | SHA256 | | --- | --- | --- | | [ABJ](https://www.amplesound.net/en/Main_Panel_Manual-ABJ.pdf) | 2025-04-16 05:04:25 | `9291c4e3027ac1469bd845bb04614f5a2754bd35a4f017bcfd7cdb75db335e7e` | | [AGLP](https://www.amplesound.net/en/Main_Panel_Manual-AGLP.pdf) | 2025-09-08 09:00:15 | `7b28b62f3c25ecb774227b15beab06f5e0f0c944f35db9e82121028017f9cedb` | | [AGM](https://www.amplesound.net/en/Main_Panel_Manual-AGM.pdf) | 2025-09-08 09:00:15 | `449bd7b8bca7771dbf8e08e0029d2bbe999f991efe441d7900ee93da29dd86a4` | | [AGT](https://www.amplesound.net/en/Main_Panel_Manual-AGT.pdf) | 2025-09-08 09:00:02 | `2e5696d750841a47061d37737ec7d8435cb4e30756cda15596d1f89ff87810dd` | | [AME](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf) | 2025-09-08 09:00:39 | `ab482f08b0546eca0a4233b8be3776c411b77f3dca96979f529debc2dfc0c4ca` | | [AMR](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf) | 2025-04-16 05:04:22 | `833115ed9d650d9d7dc0a60695a5405f2dca8cf7f0e3e4b7c7bbf6e0baa65428` | | [Settings/CPC](https://www.amplesound.net/en/Settings_and_CPCv2.pdf) | 2026-06-16 17:25:14 | `d36c4bed2d24da060588230ea7526b7a08fb9346a8b00d8adb622eaecc36bce3` | - ABJ pp.6-7 §§2.2.1-2.2.4: Sustain C0, B0-E4, velocities 1-125; 126-127 Accent; PM D0, E1-D4, high-velocity PM/low-velocity dead notes, but **no numeric dividing threshold**. No product-specific absolute anchor was established in iteration 3. Iteration 4 above resolves the Sustain anchor using the explicitly shared ABJ/ABP demo; dedicated PM remains unsupported. - AGM pp.6-7 §§2.2.1-2.2.4 and AGT pp.6-7 §§2.2.1-2.2.4: Sustain C0/PM D0, both E1-C5; sustain 1-126, 127 Pop; PM depth follows velocity. No product-specific numeric anchor obtained in this bounded pass. Iteration 4 above resolves AGM via direct switches and AGT via named A6=105; shared vendor note labels alone were not used as numeric evidence. - AMR pp.6-7 §§2.2.1-2.2.4: Sustain C0 A0-E4, 64-126 Sustain/127 Accent, 32-63 PM/1-31 dead; dedicated PM D0 B0-E4 has an unspecified high/low split. No product-specific numeric anchor established. The PDF calls itself "Ample Metal R"; the catalog retains the vendor site's Ray5 identity. Unavailable; a future supported velocity-only subset still needs that anchor. - Settings/CPC pp.7-9 §§1.2.2-1.2.9 documents single/per-string channels, MIDI Guitar mode, configurable velocity thresholds and accent settings; pp.14-15 §1.5 documents user CC assignments. No standard numeric C0 anchor or keyswitch pulse minimum was found. These settings constrain scope, not justify invented CCs or plugin-certified timing. - [SD3 manual](https://www.toontrack.com/manual/superior-drummer-3/): simplified fetch **and rendered page** require login; stopped without bypass. The accessible vendor-hosted [Example-Layout.pdf](https://www.toontrack.com/app/uploads/topic/how-can-i-use-midi-or-notaion-created-in-notion-6-to-drive-superior-drummer/pdf/Example-Layout.pdf), page 1, is a rendered SD3 **Hansa - Marble Room** layout, not a documented universal/core default map. It explicitly shows Kick Open 36, Snare Center 38, Hi-Hat Closed Tip 42 (and C0=24 in that diagram). HTTP Last-Modified 2026-03-04 08:25:19 GMT. It is a forum attachment; default-state authorship, core-library applicability, velocity and controller assumptions are not established. Public forum search corroborates 36/38/42; visible topic bodies/replies are login-limited. Do **not** promote this Hansa-specific example or General MIDI convention into an SD3 core/installed map. SD3 stays unavailable. Needed: authorized default layout for the chosen library/map, velocity/hi-hat control scope, and installed configuration/application checks. All six official main-panel PDFs and Settings/CPC were consulted, not just search summaries. Rendered vendor links supplied what simplified fetch omitted. No products were installed, private directories scanned, credentials requested, access controls bypassed, or manual/native assets retained. ### Compatibility policies, not published requirements The admitted guitar profiles require default tuning/mapping/velocity thresholds, instrument (not Strummer) mode, MIDI Guitar mode off, and an isolated idle receiver with no external held keyswitches or custom remapping. They use no guessed CCs, program changes or per-string routing. Lead routes on zero-based channel 0 (display channel 1); the host must route/accept it explicitly. At 960 PPQ, use switch velocity 100 (present in vendor examples), **120 ticks advance/30 ticks pulse**. Advance/pulse are conservative deterministic writer policies, not measured/certified vendor minimums. They are tempo-relative, not a promise of real-plugin latency compensation; the 480-PPQ demo timings are evidence of pulses, not the selected writer timing. Switches release before musical onset. Unknown initial articulation (`null`) selects **only the first requested state**, never an unconditional Sustain-plus-PM combination. Repeated latches suppress duplicates; incompatible overlapping state windows fail rather than change timing. No final articulation reset is guessed; every emitted switch is released and the last selection stays latched. `DocumentedProfileMidiTests` exercises all five admitted capabilities, first Sustain/PM where supported (ABJ Sustain only), numeric pitch/velocity boundaries, repeated latching and transitions through actual file writing/read-back, checking channels/order/timing/pairing and source immutability. These are source/format tests, not audible plugin checks. ## Earlier vendor documentation and screenshot review (2026-10-20) The following records the earlier limited review; the anchored subset and current admission decisions above supersede its former empty-catalog gate. The official manual links were discovered through Ample's rendered website and the PDFs were read locally. The earlier simplified HTML retrieval did not expose these links; that was a retrieval limitation, not evidence that documentation was unavailable. Documentation research is the assistant's responsibility; the owner need not reconstruct published mappings through tooltip screenshots. Primary sources: - [Ample Metal Eclipse main-panel manual](https://www.amplesound.net/en/Main_Panel_Manual-AME.pdf), sections 2.2.1-2.2.4 (PDF pages 6-7). - [Ample Metal Ray5 main-panel manual](https://www.amplesound.net/en/Main_Panel_Manual-AMR.pdf), sections 2.2.1-2.2.4 (PDF pages 6-7). This is the vendor's documented Ray5 target; the owner's installed bass identity/version is not yet confirmed. - [Ample Riffer 4 manual](https://www.amplesound.net/en/Guitar_Riffer.pdf), section 4.4.3 (PDF page 28). Both instrument manuals label Sustain with keyswitch C0 and Palm Mute with D0. The owner's Eclipse screenshots corroborate those labels and identify the open instrument as Ample Metal Eclipse. They also show Natural Harmonic C#0, Slide In/Out D#0, Legato Slide E0, Hammer-On/Pull-Off F0, Tap F#0 and Pinch Harmonic G0. Recording these labels does not implement extra articulations. Eclipse's documented Sustain selection uses note velocities 1-15 for full mute, 16-31 for three-quarter mute, 32-63 for half mute and 64-126 for sustain; velocity 127 has a settings-dependent accent effect. Palm Mute depth increases as velocity decreases. The owner's tooltip calls the high-velocity effect Accent; the manual describes Pop/Pinch Harmonic depending on settings. Do not assume those version/settings-dependent effects are identical. Ray5's documented Sustain selection uses 1-31 for dead notes, 32-63 for palm mute and 64-126 for sustain, with accent at 127. Its dedicated D0 selection also distinguishes high-velocity palm mute from low-velocity dead notes, but the cited paragraph does not give a numeric threshold for that split. These are vendor note labels and documented velocity facts, not a verified conversion of C0 to an absolute MIDI number. The reviewed sections do not establish all switch velocities, lead times, pulse/hold durations, initial state or release behavior required by the current profile contract. Do not fill such fields with invented constants or confuse documented defaults with verification of the owner's installed configuration. Riffer documents SMF type 0/1 import with only one track. A combined multi-role Cubase MIDI arrangement must therefore not be assumed directly importable into Riffer. This is a MIDI import capability, not an AGP serialization specification. The [SD3 online manual](https://www.toontrack.com/manual/superior-drummer-3/) still requires login in the available browser session. No account credentials are needed or requested; selected SD3 library/map and any custom overrides remain unresolved. Native AGP/SDP schemas and application acceptance remain separate gates. No production catalog data changed during that earlier review. The generic mechanism fixtures are invented **Synthetic** test/pipeline/catalog identities, not vendor mappings or acceptance evidence. No synthetic profiles are embedded in production. New documented-profile tests separately exercise the admitted vendor facts above. Step 8's two MCP tools expose only admitted production profiles and actual MIDI/fallback output, never synthetic fixtures. ## In-process boundaries - Core `InstrumentProfileValidator.Validate(profile)` rejects unverified and synthetic profiles by default. `allowSynthetic: true` is an explicit testing opt-in; it does not bless unverified profiles or bypass other validation. - Core `ArticulationPlanner.Plan(composition, profiles)` revalidates its input composition and explicit profiles, returning either a complete immutable `MidiEventPlan` or diagnostics and a null plan. It never mutates the composition. - Generation `InstrumentProfileCatalog.LoadEmbedded()` loads only the assembly resources, cross-validating every profile against the declared identity, role and exact product name. Dangling references or mismatches fail the whole load. The stream parsers are internal and exposed to unit tests only. There is no filesystem/network profile discovery, vendor scanning, runtime editor or plugin system. - `catalog.Select(role, id)` requires an exact matching role/ID. A missing ID reports `no_default_profile`; an unknown ID reports `unknown_profile`, and an existing wrong-role ID reports `profile_role_mismatch`. No defaults are currently authorized and there is no synthetic/sustain fallback. - `catalog.SelectInstrument(role, instrumentId, profileId?)` distinguishes `unknown_instrument`, `instrument_role_mismatch`, `mapping_unavailable`, `unknown_profile`, `profile_role_mismatch`, `profile_instrument_mismatch` and `ambiguous_profile`. A known instrument with one admitted candidate can select it; multiple candidates require an explicit exact profile ID, never the first item or another guitar/bass. An explicitly empty profile ID fails as `no_default_profile`; no instrument/profile defaults are silently substituted. - A missing, malformed or invalid embedded resource throws `InvalidDataException`, not a successful empty catalog. JSON uses camel-case property names and string enums, requires every non-optional constructor field (including explicit nullable fields), rejects null required values, unknown/duplicate properties and integer enums, and validates every profile/definition. Composite/numeric roles are invalid. Legacy profiles can omit optional `compatibilityNotes`; Documented profiles cannot. Present notes require all four fields; missing/blank/invalid fields fail instead of acquiring defaults. Documented primary sources must be absolute public HTTP(S) URLs without credentials. An intentional empty JSON list is valid; profile enumeration is ordinal by ID. Core has no DryWetMIDI dependency. These are typed **event intentions**, not SMF bytes or MIDI-library objects: `PlannedNoteOn`, `PlannedNoteOff` and `PlannedControlChange`, with absolute ticks, channel, pitch/velocity or CC number/value. `IsKeyswitch` distinguishes control notes from musical notes; `IsReset` distinguishes initialization/release/reset controls. Step 5 now translates these intentions through DryWetMIDI 8.0.3 in Generation's `MidiEventBuilder`, `MidiFileBuilder` and `MidiFileWriter`, with actual file write/read-back tests using the extracted test-only synthetic pipeline profiles. Core still has no library dependency. No native serialization or public generation tools exist alongside five documented default capabilities. ## Profile fields | Field | Meaning and constraints | | --- | --- | | `id` | Stable nonempty ASCII letters/digits/dash/underscore/dot; catalog IDs unique | | `instrumentId` | Required stable ASCII ID with the same shape; must reference a declared instrument at catalog admission; no inferred/default binding | | `role` | Existing `Lead`, `Bass` or `Drums` typed role; exactly one matching profile per selected track | | `productName`, `productVersion`, `mappingVersion` | Nonempty exact identity, honest version/default scope and independent mapping revision; product name matches the definition display name | | `evidence` | `status` (`Unverified`, `Verified`, `Synthetic`, `Documented`), nonempty `source`, `authorization`, `verificationRecord`; Documented is cited defaults, Verified is application-verified | | `compatibilityNotes` | Immutable string record: `versionScope`, `configurationRequirements`, `routingPolicy`, `timingPolicy`; required for Documented, optional for legacy Verified/Synthetic; fields must be nonempty, trimmed, without control characters | | `minimumPitch`, `maximumPitch` | Inclusive ascending absolute MIDI playable range, 0..127 | | `channel` | Explicit zero-based MIDI channel, 0..15; independently controlled tracks cannot share a channel | | `initialArticulation` | Null means unknown receiver articulation, forcing the first requested latched selection; a non-null pitched value declares known resting state and must be supported, never momentary; drums require null | | `initialControllers` | Complete explicit initial state for all CC numbers used by rules; emitted at tick zero | | `finalResetArticulation` | Optional explicit latched rule to restore after all musical/control releases; null means no articulation reset | | `finalControllers` | Optional explicit final CC resets; no undeclared controller or contradiction with a final articulation rule | | `rules` | Nonempty unique articulation/voice rules, as below | Synthetic IDs must begin `synthetic-` and product names `Synthetic `. Constructors snapshot input lists; profiles, rules, results and event collections are read-only. Verification status is provenance metadata, not a cryptographic attestation: editing a status to `Verified` cannot establish real-world correctness. Production resource changes require evidence review; the five bounded documented capabilities above do not assert full application compatibility. All pitches are absolute numbers. Octave labels never determine switch values. Every keyswitch must be outside the **entire** playable range, not just absent from the particular composition. Drum rules map existing logical voices to distinct absolute playable pitches; no GM/SD3 assumption is made. ## Rules, velocity and state A rule contains typed `articulation`, nullable `voice`/`drumPitch`, `behavior`, nullable `keyswitch`, a required `velocity` layer and explicit `controllers`. Pitched rules have null voice/drum pitch. Drum rules have a defined voice and mapped pitch, using the existing sustain intention (logical hits carry no separate pitched articulation). Unknown articulations/voices fail explicitly. The smallest supported velocity contract is an **inclusive requested-velocity interval** `minimum..maximum`, inside 1..127. A request outside that interval fails with `velocity_layer_conflict`; it is never clamped. Null `outputVelocity` preserves musical dynamics. A non-null output explicitly transforms every valid requested velocity to that one value, which must itself lie within the interval. This transformation is visible in the profile and event plan, not a mutation of the source note/hit. No interpolation, inferred sample layers or randomization. Different articulations with identical control state need disjoint velocity intervals. State-free disjoint layers can coexist on different musical pitches. For example, **test-only** disjoint layers 1..63 (sustain) and 64..127 (palm mute) accept their exact boundaries. Sustain at 64 fails. An explicit palm-mute output of 100 preserves the source requested velocity while emitting 100. The supported channel-wide state schemes are deliberately bounded: - `None`: no keyswitch/CC actions; velocity-only rules need no global state. - `Latched`: keyswitch actions are fixed-duration note pulses. State is the switch **pitch and velocity**, plus the complete CC number/value vector. Emit changes only when this state differs. A repeated identical articulation does not repeat the switch or CC. Every rule in a latched scheme must specify its complete state; if switches are used, sustain also needs an explicit switch. A declared initial switch state is assumed known, not needlessly re-triggered (backward-compatible known-state behavior). Null means unknown: the first requested switch is emitted, without a preliminary sustain switch. Initial CC state is always emitted explicitly. - `Momentary`: each musical note re-triggers its switch/CC actions, even for a repeated articulation. Hold the switch until both the musical note ends and its configured minimum switch duration has elapsed. Then emit its note-off and restore the explicitly declared initial CC values. A state-free resting rule expresses sustain after release; no guessed sustain keyswitch is sent. `keyswitch` holds absolute pitch, sounding velocity 1..127, nonnegative `advanceTicks` and positive `durationTicks`. Timing is exact integer ticks at 960 PPQ. For latched actions duration is the pulse length; for momentary actions it is the minimum hold measured from switch-on, **including advance**. CC actions occur at the same activation time as the associated keyswitch, or at the musical start for CC-only rules. CC numbers/values are 0..127, unique within a state. Mixed latched/momentary control schemes on one channel are unsupported. Drum profiles support voice pitches plus latched/momentary complete CC state; pitched keyswitch state is not a drum mechanism here. Overlapping momentary requests are rejected, even for identical state, because retrigger/release ownership would be ambiguous. There is no channel-per-note workaround. ## Shared timing, transitions and extent The planner computes the largest configured switch advance among **requested rules on selected tracks**, using one `LeadInTicks` for the whole arrangement. All musical starts and ends receive that same offset. Controls are scheduled at `shifted musical start - advance`, never clamped to zero. Unselected profiles/ unused rules do not increase lead-in. CC initialization alone remains at zero. The planner checks overlapping control windows (activation through musical end, or later minimum hold/pulse end). Conflicting channel-wide states fail with `conflicting_articulation_state`. Thus a nonzero-advance transition cannot silently change state during a previous incompatible sustained note: provide enough gap or a separately verified representable mapping. Identical latched states can support chords; overlapping identical musical pitches cannot be paired unambiguously and are rejected. Overlapping switch pulses also cannot create stuck/re-triggered same-pitch controls. Ordering is stable by absolute tick, then priority, retaining deterministic insertion order for ties: 1. Musical and switch note-offs (priority 0). 2. Initial/release/reset CCs (priority 1). 3. New CC state and switch note-ons (priority 2, CC vector before switch). 4. Musical note-ons (priority 3). At a shared note boundary, releases/resets therefore precede the next state and musical onset. Final resets are only those explicitly requested by the profile. They occur after the declared shifted musical extent and any later releases; a final latched reset pulse includes a matching note-off and can extend the plan. No unrequested “all notes off” or controller resets are injected. `MusicalExtentTicks` is the exact unshifted declared bar extent, including trailing rests. `MusicalEndTick` adds the shared lead-in. `EndTick` is the maximum of that end and all required control/release/reset events. Checked Int64 timing includes advance, note ends and final pulses. Range/timing/profile/state errors yield no usable partial plan. Pairing validation rejects overlapping pitch ownership and unpaired note-offs before success. ## MIDI translation boundary (Step 5) The writer accepts a validated composition and its matching event plan, not instrument names or guessed mappings. It preserves the planner's event order, absolute pitches, transformed output velocities, channels (including the synthetic drum channel 9), switches, explicit note-offs and CC state. It does not reconstruct articulations through a high-level note helper or inject all-notes-off. SMF cannot retain the internal `IsKeyswitch`/`IsReset` flags; read-back tests distinguish controls from musical notes using the known plan. Type-1 output has a tick-zero conductor, selected role tracks at 960 PPQ and one End-of-Track per track at the global `EndTick`. Exact metadata, limits, borrowed streams, safe no-overwrite same-directory staging and cancellation boundaries are documented in [the MIDI API guide](../README.md#in-process-standard-midi-generation). DryWetMIDI 8.0.3 supports actual meter denominators through 128; Core-valid /256 fails explicitly at the writer. Four-byte VLQ gaps are checked before output; the conductor's end gap bounds global `EndTick` to 268435455 ticks. Synthetic format tests are not mapping admission or plugin acceptance. The combined conductor-plus-role arrangement is not the single-track Riffer import documented above, and no AGP/SDP or Riffer-specific export is implemented. ## Remaining production gate The five admitted capabilities meet a **documented-default source/format** milestone, not full requested-target or application compatibility. Obtain the missing AMR numeric anchor/thresholds and authoritative SD3 library/map scope; ABJ's dedicated PM threshold is still absent and PM is not advertised. For application-verified readiness, obtain exact installed product/version/settings for each selected Ample target and SD3; the actual SD3 library/map/overrides; authorized versioned mapping provenance; verified playable pitches, switch pitches/velocities, layers, CC combinations, timing/durations, channel behavior, initial/latch/momentary/reset semantics; and repeatable real-application verification. Native schemas, lawful fixtures/ template rights, extension/entity semantics and Cubase/plugin import acceptance remain separate missing gates. Passing synthetic tests does not satisfy any of those production evidence requirements. The approved generic Step 5 sequencing does not authorize guessed production profiles, native writers or public tools.