@maccesar/titools 5.2.4 → 5.3.0

package/skills/ti-synthengine/references/sound-api.md

@@ -0,0 +1,197 @@
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/sound-api.md` SHA-256: `bb7bfe10a63aba700bdd3584e803436852e07200b82798f5f16c83383687a546`.
+
+# Sound objects: TiSynth 2.0.0
+
+TiSynth 2.0.0 provides reusable sound definitions and independent playback controls on Android and iOS. `createSound()` allocates no voice. Its definition survives `shutdown()` and can play again after `start()`. Rendering, gain, admission limits and scheduling use the existing native tone, chord, held, repetition and sequence paths.
+
+TiSynth uses one version: the installed module version. Both `getContract().version` and `getDefaults().version` report `2.0.0`. `getContract()` also describes `capabilities.soundObjects: true`, supported interpretations, property names and units.
+
+## First sound
+
+```javascript
+const synth = require('ti.synthengine')
+const contract = synth.getContract()
+if (contract.version !== '2.0.0') throw new Error('Sound objects require TiSynth 2.0.0')
+if (!synth.start({ maxVoices: 16, maxSequences: 4, mixingProfile: 'conservative', audioSession: 'ambient' })) {
+  throw new Error('Audio startup rejected')
+}
+const bell = synth.createSound({
+  name: 'Bell',
+  sound: { waveType: contract.waveTypes.SINE, volume: 0.25, attack: 5, release: 120 },
+  playback: { type: 'tone', notes: ['A4'], duration: 400 }
+})
+if (!bell.play()) throw new Error('Bell rejected')
+bell.play({ notes: ['C5'], volume: 0.15 })
+synth.setVolume(0.8)
+synth.setTempo(110)
+```
+
+Start the engine after the owning screen has settled, and call `shutdown()` when its audio owner closes. Follow the [lifecycle guidance](guide.md#lifecycle) and plan the [voice budget](recommendations.md). A later higher-priority event can replace a finite event that was accepted earlier.
+
+## Stored definitions and temporary overrides
+
+A preset has optional `name`, `sound` and `playback` dictionaries. `sound` holds synthesis and routing; `playback` holds pitch and interpretation. `getPreset()` returns a detached copy, preserving whether `type` was authored or inferred. Inputs are copied too.
+
+`Sound.set({ sound, playback })` recursively merges objects, replaces whole arrays and validates the complete result before replacing the stored definition. A failed change throws without partially applying it. `null` removes an optional leaf when the remaining preset is valid; it does not remove a whole `sound` or `playback` dictionary. Arrays, including `steps`, `notes`, `frequencies`, `waveTable`, `modulations` and variation ranges, replace the complete array; they do not concatenate. `set()` affects future executions; it does not edit controls already playing.
+
+`Sound.play(changes)` and `Sound.noteOn(changes)` accept **flat** overrides, such as `{ notes: ['D4'], volume: 0.2 }`. They do not accept nested `{ sound, playback }` arguments. An execution never mutates the stored preset. Repetition and pattern updates also accept `null` to remove an optional leaf when the complete resulting revision is valid. Such resets replace the native recipe without restarting its transport or repetition deadline. Held-note updates require concrete live values; use supported disabling values such as zero or an empty modulation array. Setting `notes` replaces a previously stored `frequencies` source and vice versa; supplying both together throws.
+
+```javascript
+const sound = synth.createSound({
+  sound: { volume: 0.3, pan: 0.2, variation: { amount: 1, ranges: { volume: [0.2, 0.3] } } },
+  playback: { notes: ['C4'], duration: 300 }
+})
+sound.set({ sound: { pan: null, variation: { amount: 0.5 } } })
+sound.set({ playback: { notes: ['D4'] } })
+const preset = sound.getPreset()
+// The volume range is retained; pan is absent; notes is now exactly ['D4'].
+if (preset.sound.pan !== undefined || preset.playback.notes.length !== 1) throw new Error('Unexpected preset')
+sound.play({ notes: ['E4'] })
+```
+
+Unknown keys, wrong types, incompatible fields and out-of-range values throw descriptive `TypeError`s before publication. Fields are never silently stripped to make a definition valid. Numeric ranges and waveform-dependent rules remain those in the [native reference](api.md#strict-validation). Operational failures, including an unavailable engine or a rejected publication, return `false`.
+
+## Interpretations and returns
+
+An explicit type on the call wins over the preset's declared type. If neither declares a type, `steps` infers a pattern, more than one pitch infers a chord, and otherwise a tone is inferred. Inference never writes a type into the stored preset. Repetition and held interpretation require an explicit type, or `noteOn()` for held execution.
+
+| Type or method | Accepted return | Playback fields | Native path |
+| --- | --- | --- | --- |
+| `tone` | `true` | `notes` or `frequencies`, `duration`, `frequencyEnd` | One finite tone |
+| `chord` | `true` | `notes` or `frequencies`, `duration` | Atomic finite chord, including an explicitly declared one-note chord |
+| `repeat` | Repetition control | Single pitch, `duration`, `frequencyEnd`, required `interval` | Native finite-tone repetition |
+| `pattern` | Pattern control | `steps`, `interval`, `timeUnit`, `gate`, `loop`, `swing`, `mode`, `tuning`, optional root `frequencyEnd` | Native sequence |
+| `held` or `Sound.noteOn()` | Note control | Single pitch only | Existing sustained voice |
+
+All executions can return `false` on operational rejection. Finite tones and chords expose no individual control or identifier. A declared type remains in force when pitches change: `type: 'tone'` with two notes throws; an explicit `type: 'chord'` with one note retains chord gain and admission behavior. Choosing another type does not discard incompatible preset fields: clear or replace them in the definition first.
+
+Use either `notes` as note names or integer MIDI notes 12 through 119, or `frequencies` in hertz. Tone, held and repetition use one-element arrays. Chords use 1 through 32 pitches. Numeric pitches in finite/held calls convert to native note names; pattern pitches remain MIDI integers. Keep duplicate pitches when unison is intentional.
+
+Each interpretation has restrictions beyond the shared sound-property allowlist below. Finite-tone endpoints cannot be used as held live controls, and the native chord validator rejects sweeps and modulations. Source rules require sine for FM, square for PWM, an active filter for filter targets, and compatible stereo or spatial controls. Use explicit `type: 'held'` when a definition contains held-only modulation or envelopes so construction validates the intended native path.
+
+## Held notes
+
+```javascript
+const heldSound = synth.createSound({
+  sound: { waveType: 0, volume: 0.2, fmRatio: 2, fmDepth: 1, attack: 10, release: 160,
+    modulations: [{ target: 'fmDepth', wave: 'sine', rate: 2, depth: 0.1 }] },
+  playback: { type: 'held', notes: ['C4'] }
+})
+const note = heldSound.play()
+if (note) {
+  note.update({ notes: ['D4'], volume: 0.15, fmDepth: 0 })
+  if (!note.noteOff()) throw new Error('Note release rejected; owner must retry or close audio')
+}
+const anotherNote = heldSound.noteOn({ notes: ['E4'] })
+if (anotherNote) anotherNote.noteOff()
+```
+
+Each start returns an independent `{ update, noteOff }` control with private identity. No `voiceId` is accepted or exposed. `noteOn()` always uses the single-note held path, even when called on a finite preset; finite `playback.duration` and `playback.frequencyEnd` are not applied to that held execution. Incompatible synthesis leaves, such as `sound.panEnd`, still throw rather than being discarded. It accepts flat synthesis and live pitch overrides, not `type`, `duration` or `frequencyEnd`.
+
+`Note.update()` accepts `notes` or `frequencies`, `volume`, `pan`, `lfoFreq`, `lfoDepth`, `noiseRate`, `lowPassHz`, `pulseWidth`, `filterHz`, `filterQ`, `fmRatio`, `fmDepth`, `spatialX`, `spatialY`, `effectSend` and `modulations`. Only compatible source controls can change; variation, waveform, attack/release, bus and priority are not live fields. Live FM depth can reach zero. Updates retain phase and envelope, using the existing native 10 ms transition. They validate the live patch without requiring attack-only settings again.
+
+Release on touch cancellation, pause and owner teardown. A rejected release remains retryable; the [held ownership guidance](guide.md#hold-and-edit-a-voice) describes bounded recovery. After an accepted release, that control no longer updates or releases a second time. Ended or stolen voices retain the native no-op edit behavior while their control generation remains valid.
+
+## Repetition
+
+```javascript
+const pulse = synth.createSound({
+  sound: { waveType: 1, volume: 0.15, attack: 2, release: 40 },
+  playback: { type: 'repeat', frequencies: [440], duration: 120, interval: 200 }
+})
+const repetition = pulse.play()
+if (repetition) {
+  repetition.update({ frequencies: [660], interval: 180 })
+  repetition.stop()
+}
+```
+
+A repetition exposes `{ update, stop }`. `interval` is integer milliseconds from 1 through 60000. Each attack retains finite-tone duration, envelope and sweep semantics. An update affects the next scheduled attack without moving its existing deadline; the edited interval controls the following gap. Already admitted attacks retain their original recipe. `stop()` cancels future attacks while admitted finite attacks finish. Repetition has no end event and uses its existing capacity independently of pattern slots. Shared voice admission still applies to each attack.
+
+## Patterns
+
+```javascript
+const melody = synth.createSound({
+  sound: { waveType: 3, volume: 0.2, attack: 5, release: 80, bus: 'music', priority: 2 },
+  playback: { type: 'pattern', timeUnit: 'beats', interval: 0.25, loop: false,
+    steps: [{ notes: ['C4'] }, { notes: [64], interval: 0.5, sound: { volume: 0.15 } },
+      { rest: true }, { notes: [60, 64, 67], length: 0.4 }] }
+})
+const pattern = melody.play()
+if (pattern) {
+  pattern.addEventListener('end', event => {
+    // event.reason is 'completed' or 'stopped'. Release and effects may remain audible.
+    Ti.API.info(event.reason)
+  })
+  pattern.update({ swing: 0.1 })
+  const state = pattern.getState()
+  if (state) Ti.API.info(state.step)
+  pattern.stop()
+}
+```
+
+A pattern exposes `{ update, stop, getState, addEventListener, removeEventListener }`. The event name is `end`; its payload is `{ reason: 'completed' | 'stopped' }`, with no native identifier. A control receives completion at most once. `getState()` returns the existing applied transport state with `sequenceId` removed, or `null` when unavailable. Removing a listener requires the same function reference.
+
+Root and per-step `interval` specify time until the next attack. `length` still controls sounding length; omitting it uses `gate`. A step contains exactly one of `notes`, `frequencies` or `rest: true`, with optional `interval`, `length`, `gate` and `sound`. Per-step `sound` supplies synthesis settings for that attack. Root `sound.detune` applies the pattern pitch rule. Root `playback.frequencyEnd` maps to the native voice endpoint, while a per-step endpoint belongs in `steps[i].sound.frequencyEnd`.
+
+`timeUnit` is `beats` by default or `ms`, and stays fixed during playback. Root interval defaults to 0.25 beats or 100 ms. Patterns contain up to 512 steps and 32 pitches per sounding step, with the existing swing, mode, revision and capacity rules. Updates replace arrays and preserve native revision scheduling; they do not restart transport. Pattern `stop()` remains accepted before its native slot is retired. Coalesce replacements and wait for the owned control's `end` event before publishing the next score when capacity is occupied. An `end` event marks transport retirement, not audible silence: release and processing tails may continue.
+
+## Units and processing
+
+| Quantity | Unit and meaning |
+| --- | --- |
+| `sound.attack`, `decay`, `release` | Milliseconds in every interpretation |
+| Tone, chord or repetition `playback.duration` | Total milliseconds including release, including the complete finite envelope |
+| Tone or repetition `playback.frequencyEnd` | Hertz; native finite sweep endpoint |
+| Repetition `playback.interval` | Integer milliseconds, independent of global tempo |
+| Pattern root/step `interval` and step `length` | Beats or milliseconds according to the pattern's `timeUnit` |
+| Pattern `frequencyEnd` | Hertz; native note-length sweep timing with release afterward |
+| `setTempo(number)` | Beats per minute, 20 through 300 |
+| `setProcessing().delay.time` | Milliseconds, 20 through 2000 |
+| `setProcessing().reverb.decay` | Milliseconds, 200 through 8000 |
+
+Finite and pattern envelopes are different native paths. Converting a finite total duration of 150 ms with 25 ms release to a millisecond pattern requires `length: 125` and `release: 25` to preserve that sounding lifetime; attack spacing is a separate `interval`. Do not replace grouped chords with independent tone starts or convert repetition into a sequence when preserving the original gain and envelope interpretation.
+
+```javascript
+synth.setProcessing({ inputGain: 1, applyTo: ['music'],
+  delay: { enabled: true, time: 250, feedback: 0.25, mix: 0.1 },
+  reverb: { enabled: true, decay: 1500, damping: 0.6, mix: 0.12 } })
+synth.enableStats()
+const statistics = synth.getStats()
+synth.disableStats()
+```
+
+`setProcessing()` uses the shared effects chain and strict native validation. Supply delay `time` and reverb `decay` in milliseconds. The adapter converts them to native `timeMs` and seconds-based decay. Other chorus/delay/reverb/saturation, `inputGain` and `applyTo` fields retain the [processing reference](api.md#setmasterprocessingoptions) ranges and semantics.
+
+`bus`, `effectSend` and `priority` belong to `sound`, including a step's `sound` where supported. Routes, sends, fixed per-event gain and chord grouping are unchanged. Sound creation does not enable diagnostics; use `enableStats()` and `disableStats()`, and retain unavailable readings as `null`.
+
+## Lifetime and errors
+
+A Sound is reusable across engine shutdown/start; a playback control is bound to the generation that created it. Shutdown invalidates old controls, which subsequently return `false` for updates/releases/stops and `null` for pattern state. They cannot affect a new execution or a reused app identifier. Stale completion/invalidation events cannot retire a new generation's pattern. Listener installation on an invalid pattern has no effect. `stopAll()` retains its global panic behavior; prefer an owned control for ordinary release or cancellation.
+
+The [upgrade guide](upgrade-2.0.0.md) records method mappings and metadata changes. Global `setVolume()` and `setTempo()` return Boolean acceptance. Sound and `setProcessing()` reject invalid configurations with descriptive errors.
+
+The [TypeScript declarations](../assets/index.d.ts) describe Sound definitions, controls and the supported direct methods. `Sound.play()` has a mixed return when the stored interpretation is not known at the call: narrow the result before calling a control method, or supply an explicit call `type`. Runtime validation remains authoritative for numeric ranges and combinations.
+
+## Property allowlists
+
+`getContract()` reports these shared structural allowlists. Native validators then apply each interpretation's compatibility rules.
+
+### Sound properties
+
+| Keys | Purpose |
+| --- | --- |
+| `attack`, `decay`, `sustain`, `release`, `volume`, `waveType` | Envelope, gain and source |
+| `pan`, `panEnd`, `pans`, `panSpread`, `spatialX`, `spatialY` | Stereo or spatial placement |
+| `lfoFreq`, `lfoDepth`, `noiseRate`, `noiseRateEnd`, `lowPassHz` | Vibrato and noise shaping |
+| `pulseWidth`, `pulseWidthEnd`, `waveTable`, `bitDepth` | Wave shaping |
+| `filterType`, `filterHz`, `filterHzEnd`, `filterQ` | Resonant filter |
+| `fmRatio`, `fmDepth`, `fmDepthEnd`, `detune`, `detunes`, `modulations` | Pitch, FM and compatible LFOs |
+| `bus`, `effectSend`, `priority`, `variation` | Routing, admission and native variation |
+
+### Playback properties
+
+| Keys | Purpose |
+| --- | --- |
+| `type`, `notes`, `frequencies`, `frequencyEnd`, `duration` | Interpretation, pitches and finite timing |
+| `interval`, `timeUnit`, `steps`, `gate`, `loop`, `swing`, `mode`, `tuning` | Repetition or pattern scheduling |

package/skills/ti-synthengine/references/sound-design.md

@@ -1,11 +1,11 @@
-> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.0. Upstream `documentation/sound-design.md` SHA-256: `3ad60c006e6ba296110b73362ebba74a30fd5e722fae6c5066cec815e500262a`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/sound-design.md` SHA-256: `41f294143b8a4bb8cbee550a66b51768c13a583c94e1f7f810dfdeb471f14922`.
 
 # Sound design with TiSynthEngine
 
-TiSynthEngine generates sound with oscillators, without recorded samples. Pitch, waveform, envelope, movement and level define each sound, from interface feedback and musical cues to alarms, retro effects and simple percussion.
-
 Additional [curated recipes](recipes.md) provide application sound and interaction variants.
 
+TiSynthEngine generates sound with oscillators, without recorded samples. Pitch, waveform, envelope, movement and level define each sound, from interface feedback and musical cues to alarms, retro effects and simple percussion.
+
 For the distinction between a playable timbre and a complete effect recipe, start with [instruments, sound effects and complete sequences](instruments-and-effects.md). It covers held keys, independent shots, native sequences, layered effects, demonstrations and shared output headroom.
 
 The examples assume the engine is running and use these constants:
@@ -67,7 +67,7 @@ Equal temperament keeps intervals consistent in every key. It also means a major
 
 ## Waveform and timbre
 
-Pitch says how fast the oscillator repeats. Waveform says how it moves within each cycle, which determines the harmonic content and perceived timbre.
+Pitch describes how fast the oscillator repeats. Waveform describes its motion within each cycle, which determines the harmonic content and perceived timbre.
 
 ### Sine
 
@@ -79,7 +79,7 @@ Pitch says how fast the oscillator repeats. Waveform says how it moves within ea
 
 ### Sawtooth
 
-`SAWTOOTH` contains both even and odd harmonics. It is the densest pitched waveform in the module and reads as buzzy or brassy. Use it for alarms, arcade leads and short sweeps. Square and sawtooth are band-limited with PolyBLEP to reduce aliasing at discontinuities.
+`SAWTOOTH` contains both even and odd harmonics. It is the densest pitched waveform in the module and sounds buzzy or brassy. Use it for alarms, arcade leads and short sweeps. Square and sawtooth are band-limited with PolyBLEP to reduce aliasing at discontinuities.
 
 ### Triangle
 
@@ -235,7 +235,7 @@ A rate around 4 to 7 Hz with a small depth sounds like musical vibrato. A fast r
 
 `filterType` adds a filter that removes or emphasizes part of the spectrum. It has 12 dB per octave of slope, twice as steep as the one-pole `lowPassHz` filter, and can be combined with it (`lowPassHz` runs first).
 
-- `lowpass` darkens the sound. A sawtooth through a closing low-pass reads as a zap or a sound moving away; an opening one reads as a swell.
+- `lowpass` darkens the sound. A sawtooth through a closing low-pass sounds like a zap or a sound moving away; an opening one sounds like a swell.
 - `highpass` thins the sound by removing body. It makes hats, hiss and tinny effects out of noise.
 - `bandpass` keeps one band around `filterHz`, which gives vocal, nasal and wah-like colors.
 
@@ -264,7 +264,7 @@ synth.playTone({
 
 FM makes rich, bright and metallic sounds from a plain sine. A second sine, the modulator, bends the pitch of the first one, the carrier. Turn it on with `fmDepth` or `fmDepthEnd`, on a `SINE` voice.
 
-- `fmRatio` is the modulator frequency as a multiple of the carrier's. Whole numbers (1, 2, 3) keep the added overtones on the harmonic series, so the pitch stays clear and the sound reads as organ- or piano-like. Fractional ratios such as 1.4142 or 3.5 put the overtones between harmonics, which reads as bells, glass and metal.
+- `fmRatio` is the modulator frequency as a multiple of the carrier's. Whole numbers (1, 2, 3) keep the added overtones on the harmonic series, so the pitch stays clear and the sound resembles an organ or piano. Fractional ratios such as 1.4142 or 3.5 put the overtones between harmonics, giving the sound the character of bells, glass and metal.
 - `fmDepth` is the modulation index and works like a brightness control. Around 0.5 to 1.5 it warms a sine, 2 to 5 makes it bright and rich, and values near 10 get harsh.
 - `fmDepthEnd` moves the index over the event. Starting high and ending low gives a bright attack that mellows, which is the signature of electric pianos, bells and mallets. Pair it with `decay` so the level falls with the brightness.
 
@@ -341,7 +341,7 @@ Different phones have different sample rates, speaker protection and acoustic re
 
 ## Recipes
 
-These recipes use only the 1.0.0 contract and keep explicit envelopes valid. Adjust pitch and volume to fit the app's other audio; the recipe values are starting points, not mastering targets.
+These recipes use the supported direct native parameter contract and keep explicit envelopes valid. Reusable definitions put synthesis fields in `sound` and pitches/timing in `playback`; see the [Sound interface](sound-api.md). Adjust pitch and volume to fit the app's other audio; the recipe values are starting points, not mastering targets.
 
 ### Interface click
 
@@ -593,7 +593,7 @@ synth.playTone({
 })
 ```
 
-The pitch drop is the punch and the decay is the thump. A phone speaker cannot reproduce 42 Hz, so raise `frequencyEnd` toward 70 for speaker playback.
+The pitch drop creates the punch, while the decay shapes the thump. A phone speaker cannot reproduce 42 Hz, so raise `frequencyEnd` toward 70 for speaker playback.
 
 ### Simon-style cues
 
@@ -630,7 +630,7 @@ See [Examples](examples.md) for complete code and [Recommendations](recommendati
 
 ## Holding a sound and adding movement
 
-Choose a held voice when the ending follows a player action instead of a fixed duration: motor, charge beam, pad or the last chord of a ceremony. `noteOn` starts a positive app-owned ID; `noteOff` begins release from the current level, and compatible `updateVoice` edits ramp over 10 ms. Distinct IDs remain independent events with fixed gain. Reserve enough capacity for their releases and unrelated effects, and release on cancellation as well as ordinary key up. See the [held motor recipe](advanced-examples.md#sustained-game-motor) for retry/cleanup handling.
+Choose a held voice when the ending follows a player action instead of a fixed duration: motor, charge beam, pad or the last chord of a ceremony. `noteOn` starts a positive app-owned ID; `noteOff` begins release from the current level, and compatible `updateNote` edits ramp over 10 ms. Distinct IDs remain independent events with fixed gain. Reserve enough capacity for their releases and unrelated effects, and release on cancellation as well as ordinary key up. See the [held motor recipe](advanced-examples.md#sustained-game-motor) for retry/cleanup handling.
 
 A fanfare can use beat or millisecond sequences with native chords, rests, gate, independent length, swing and pitch-ordered arpeggios. A long release can ring over later steps. Use held voices when release follows presentation or interaction. See [transport usage](guide.md#choose-the-musical-transport).
 
@@ -647,4 +647,4 @@ The two additional voice LFOs move filter cutoff, square PWM or sine FM index us
 
 All processors are off initially, with input gain 1. Enable one shared chain through `setMasterProcessing`; select `applyTo` categories such as `music` and `ambience` to keep explosions dry. Per-voice `effectSend` overrides that category selection. [Configuration](advanced-examples.md#chorus-delay-reverb-and-creative-saturation) and [exact ranges](api.md#setmasterprocessingoptions) explain chorus, delay, reverb and optional saturation.
 
-Disabling an effect closes its input gradually and drains the tail before exact bypass; it does not immediately erase its history. Panic invalidates histories. Saturation is a creative choice rather than automatic gain protection; the final limiter stays in place. Match dry/wet comparison levels and watch accumulated limiter reduction so a louder version does not win an A/B comparison merely by level. None of these effects makes a small speaker reproduce missing bass.
+Disabling an effect closes its input gradually and drains the tail before exact bypass; it does not immediately erase its history. Panic invalidates histories. Saturation changes the sound and provides no automatic gain protection; the final limiter stays in place. Match dry/wet comparison levels and watch accumulated limiter reduction so a louder version does not win an A/B comparison merely by level. None of these effects makes a small speaker reproduce missing bass.

package/skills/ti-synthengine/references/source-notes.md

@@ -1,147 +1,62 @@
-# Maintaining the synthesis snapshot
-
-These references cover **published module 1.0.2 and local 1.1.0 candidates**, both with public API 1.0.0. All fifteen official Markdown documents were reviewed against the native module. Thirteen are mirrored into fourteen parts; the index and notices retain explicit reviewed exclusions. The official documentation corrections are committed at `b07c97c762be5905f132cecf33e9d60ea0c21316`. Complete source/mirror hashes are recorded in [source-snapshot.json](source-snapshot.json). Review date: 2026-11-02.
-
-## Public downloads and artifact provenance
-
-The published replacement packages were downloaded and verified on 2026-10-30 UTC (2026-10-29 locally). The following records are that historical artifact verification, not new downloads during this audit. GitHub release metadata was checked on 2026-11-02: public platform releases remain 1.0.2; local 1.1.0 candidates have no published release.
-
-| Platform | Published release | Replacement package SHA-256 |
-| --- | --- | --- |
-| Android | [android-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2) | `8698104f188782a77699fbd6308a779ca0b190833ceebf398557b628af1b8bbe` |
-| iOS / Mac Catalyst | [ios-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2) | `779e77d018d5b3f686d69cb1b4b0162281803ea12691487df565c1fd15175c58` |
-
-Both ZIPs passed full CRC checks and matched the GitHub asset SHA-256 digests at that verification. These hashes replace the original 1.0.2 packages' hashes; filenames and
-release URLs did not change. Manifests report module `ti.synthengine`, version
-`1.0.2`, minimum Titanium `13.2.0.GA`, four Android ABIs and Apple Mac Catalyst
-support. The manifest's native `apiversion` field is distinct from the JavaScript
-contract's `apiVersion: '1.0.0'`, which remains unchanged.
-
-All eight Android native libraries (inside the AAR) and three Apple static
-libraries match the preserved original 1.0.2 release packages byte for byte.
-Corrected guide, example and platform README HTML was inspected in both new
-packages. Source/package checks do not constitute a fresh device installation or
-listening acceptance. See the [guide](guide.md) for API35/iOS15 requirements,
-app-root ZIP installation and both `tiapp.xml` declarations.
-
-## Sources and permitted transformations
-
-Thirteen official Markdown documents are mirrored into fourteen parts, including the ordered examples/advanced-examples split. New references preserve the complete [instruments/effects guide](instruments-and-effects.md), [implemented variation contract](native-variation.md), [historical proposal](native-variation-proposal.md) and [variation verification](native-variation-validation.md). The proposal is historical design context, not an outstanding implementation plan. The current snapshot inventories all
-complete JSON reports, bundled example assets and linked raw-evidence archives.
-The historical [performance review](performance-review.json) and its raw archive are
-preserved alongside historical reports; none is replaced by a favorable summary.
-Read snapshot records for exact counts and hashes. Example JavaScript and raw
-reports/archives remain byte-identical to source.
-
-Each Markdown part and the example README have a committed-source provenance header and recorded navigation transformations. Verified API, timing, spatial, panic, processing and diagnostic corrections were applied to the official module documentation before synchronization. They are shared source content, not mirror-only errata. Remaining `link_fixes` record navigation and curated entry points; the source hash identifies the corrected official committed text. Reversible `link_fixes` rebase links into the split advanced examples, preserve [curated recipes](recipes.md), and resolve current example links to bundled assets. The example README points back to this skill's current API and guides. All three example JavaScript files remain byte-identical to source; none requires a historical GitHub snapshot.
-
-The fidelity regression strips provenance/navigation, concatenates example parts, reverses declared transformations and compares the complete source hash. Raw records must remain byte-identical. Update transformations intentionally; never change hashes merely to hide unexplained source drift.
-
-## Protected curated content
-
-[Retro recipes](recipes.md) and [interaction/instrument recipes](recipes-interaction.md) are TiTools contributions. Preserve their acoustic intent, lifecycle ownership and entry links when upstream docs change. Their native sequence examples keep the original millisecond onsets and total envelopes through separate `duration` and `length`; no JavaScript timer schedules notes. The repeated chord is now one centered native chord sequence; the separate one-off layered chord retains its per-voice stereo pans.
-
-Focused executable recipe tests inspect submitted intervals, envelope lengths, pitch and cancellation IDs. They do not render audio or measure native callback timing.
-
-## Current contract and acceptance boundaries
-
-`start` configures one engine, up to 32 shared voices and one to four preallocated sequence slots. `playSequence` is the only successive-sound scheduler and returns a positive ID or zero. Sequence edits, state queries and cancellation name that ID. Global `setTempo` governs beat timing and synchronized modulation; millisecond sequences retain fixed times. Finite playback is the default, and circular patterns explicitly opt into looping.
-
-Selective `music`, `effects`, `ui` and `ambience` categories feed one shared effect chain; an explicit per-voice send overrides category selection. Live spatial position, noise clock, low-pass cutoff and compatible continuous voice controls ramp over 10 ms while preserving history. Priorities protect higher-priority voices without reserved quotas. See the [API](api.md) for exact limits, source compatibility, return values and event delivery.
-
-### Module 1.0.1 and 1.0.2 corrections
-
-Michael Gangolf's [Android PR #1](https://github.com/macCesar/TiSynthEngine/pull/1)
-updates Oboe to 1.11.0, recovers closed streams after all stream errors, keeps a
-single demand-driven sequence-event poll chain and shuts down on root activity
-destruction. Removing the unused Java Thread inheritance changes no public API.
-The subsequent Apple correction polls only while sequence events or held-voice
-metadata need retirement and guards shutdown/restart reentry. Neither poller is
-a musical scheduler; explicit engine ownership/teardown remains required.
-
-Module 1.0.2 shares final output processing in `shared/synth_output.h`: zero
-retained samples, immediate stereo-linked sample protection, ceilings 0.85/0.70,
-100 ms exponential recovery and reset after two consecutive quiet stereo frames.
-Master volume ramps linearly over 10 ms on both platforms, independently of the
-protector. The iOS `raw` startup correction now applies its documented gain;
-existing raw mixes need review. Overload changes the waveform, and sample
-ceilings do not certify inter-sample peaks or speaker behavior.
-
-[Pipeline validation](audio-pipeline-validation.md) preserves the new production
-callback/CI checks, five-rate output comparisons and physical scope. Preset
-calibration measures both renderers and six scenarios at 1/2/4/8/16/32 voices;
-fixed-gain recommendations target the measured 1–8-voice configuration, with
-16/32 kept as stress diagnostics. It never edits Studio. The Android startup
-underrun remains unresolved, including independent silent Oboe reproduction.
-Route-wide latency, Bluetooth and extended maximum-load acceptance remain open.
-
-Official documentation corrections preserve panic cancellation (`stopAll` stops every
-sequence and invalidates effect histories), compatible live `updateVoice`
-noise/low-pass/spatial/send edits, and category selection with `applyTo` plus
-explicit `effectSend` overrides. The matching mirror-only errata were removed from the transformation list; curated recipe navigation remains reversible.
-Android and Apple production callback tests now run in CI; the historical Java
-DSP model is not the production audio oracle. No native binaries were installed
-or device/listening tests rerun during this skill update.
-
-### Historical evidence
-
-The [performance review](performance-review.json) documents the accepted
-control-thread changes: partial sequence-bank preparation and removal of idle
-allocations/orphan held-position metadata. The Apple rendering bundle was
-rejected after a physical stereo regression, and production returned to the
-stable callback. Earlier candidate timings and fidelity checks remain evidence
-of that rejected candidate, not a promised Apple render speedup. Current matched
-Apple bypass measurements and actual hardware/rate/block-size scope are in the
-report; global performance acceptance remains open.
-
-Historical statistics, Studio/unified transport, physical/Frontier measurements
-and Android FIR8 correction reports keep their original artifact and acceptance
-boundaries. The short Android Sim80 headphone result had zero backend xruns and
-accepted listening; it does not close the distinct ten-minute maximum-load,
-bypass, memory and strict Frontier presentation criteria. Current evidence and
-rejected candidates must not be combined into a general pass. This skill update
-did not rerun devices, install binaries or alter native source.
-
-The native differences below were rechecked against current sources on November 2 and are now documented accurately in the official API/engine guides as well as the mirrors. They describe implementation differences, not unresolved documentation contradictions:
-
-- iOS timed tone/chord command construction initially rounds accepted zero attack
-  and release to one sample before duration-budget trimming; Android preserves zero. Validator
-  acceptance does not establish identical sample envelopes.
-- iOS early tempo/sequence/processing rejections and incompatible held spatial/
-  modulation edits can bypass rejection counters. Android also leaves some
-  unknown/retired sequence-stop returns uncounted. The recorded reason sum is
-  consistent with recorded totals, not a complete API-call rejection tally.
-- Sequence cutoff coefficients currently refresh every 16 samples on Android
-  and every 8 samples on Apple; both use note length but do not promise identical
-  sample output. See [engine details](audio-engine.md).
-- Local 1.1.0 returns `capabilities.variation: true` and `variationSchemaVersion: 1` on both platforms. Android also reports native sequence/master processing/modulation flags and `limits.stepDurationMs`; iOS omits those additional entries. Published 1.0.2 does not accept variation. Both platforms return sequence-capacity, priority and send limits; use the [API](api.md) for exact beat/millisecond ranges.
-- Official examples now bind their waveform constants and document native sequence modulation, complete effect fidelity and publication ownership correctly. The mirrors preserve the same facts.
-
-
-These are official-documentation and skill corrections, not native implementation fixes. No module code, public range or hardware acceptance was changed.
-A validator corpus establishes accepted/rejected dictionaries, not sample-identical
-rendering on a physical device. Current source-first coverage ledgers and native locators are recorded in the maintainer's November 2 audit evidence.
-
-## Local 1.1.0 attack variation
-
-Both platforms validate eight bounded parameter ranges and select once per admitted attack. Require the capability/schema pair and omit the property entirely on published 1.0.2, including amount zero. The [variation guide](native-variation.md) preserves exact bounds, linear amount, pitch ratio, source prerequisites, per-chord ordinals, held stability, whole-dictionary step replacement, revision merging and deterministic seed identity. `updateVoice` rejects the attack dictionary. Preserve all of the authored envelope, cadence, routing and layer gains.
-
-The [verification report](native-variation-validation.md) separates initial host/build checks from later consumer installations and scoped listening feedback. It records the 144-byte configuration and four-transport growth from 8,627,712 to 9,537,152 bytes, excluding other engine/bridge/process storage. Earlier 1.0.2 memory reports remain historical. Host callback timings do not prove device overhead or sustained acceptance.
-
-This audit reran the paired production validators (156 cases per platform), the affected documentation checks and TiTools mirror/recipe checks. New source inspection verified sampling/admission and sequence seed identity. Historical renderer PCM, native build, consumer install and listening results were read with their original boundaries; they were not repeated or expanded into general device acceptance. No native source or binary was changed.
-
-All thirteen raw JSON/ZIP records moved upstream from `documentation/` to `docs/validation/` without changing bytes. Their distributed skill paths are preserved; the snapshot now records their actual upstream locations. All five ZIPs passed CRC checks. The three example JavaScript assets remain byte-identical; `app.js` now includes the capability-gated attack-variation action.
-
-## Upstream documents outside the mirror set
-
-The official index is replaced by this skill's task routing. Dependency/license notices remain in the official module and binary packages. Both are recorded with hashes and reasons in `excluded_documents`, so changed or newly added documents still require review.
-
-## Verification after a reviewed update
-
-Run the focused mirror/link and recipe tests, then:
-
-```sh
-node scripts/verify-module-snapshot.mjs --source /path/to/TiSynthEngine --skill ti-synthengine
-```
-
-The verifier checks source/mirror hashes, exclusions, new documents, base HEAD and the exact tracked/untracked worktree fingerprint. Refresh that fingerprint only after the source changes are finished. No npm version, publication or native-device acceptance follows from this procedure.
+# Source and platform caveats
+
+These references cover published TiSynthEngine 2.0.0, reviewed at
+`9d74aa45f84d3f2822d4aab76874efe37d81257f` on 2026-11-03. Both platform
+release ZIPs declare 2.0.0 and their packaged declarations match the bundled
+[TypeScript asset](../assets/index.d.ts). Read the [guide](guide.md) for
+installation and the [upgrade guide](upgrade-2.0.0.md) for migration.
+
+## Choose the correct interface
+
+Use [Sound objects](sound-api.md) for new code. The [direct API](api.md) remains
+supported, including its Boolean/ID return contracts and original option names.
+The [sound](recipes.md) and [interaction](recipes-interaction.md) recipes use
+that direct interface. Preserve their pitch, envelope, gain and timing when
+adapting them. A Sound definition survives shutdown, but its playback controls
+become invalid.
+Do not combine `sound`/`playback` presets with direct native dictionaries.
+
+Runtime metadata uses `version`, not `apiVersion`. Native module manifest
+`apiversion` is a separate Titanium ABI field. Older 1.0.2 binaries lack variation
+and repetition; detect methods/capabilities before sending new closed-dictionary
+fields. Native variation requires its capability and schema pair. Android reports
+some extra sequence/processing/modulation flags that iOS omits while supporting
+the methods; do not use those flags as a universal feature gate.
+
+`setProcessing()` reverb decay is milliseconds; direct `setMasterProcessing()`
+reverb decay remains seconds. See the [unit mapping](upgrade-2.0.0.md#names-and-units).
+
+## Native differences that affect decisions
+
+- Submit exact integer repetition intervals. The reviewed Apple validator accepts
+  values extremely close to an integer within its 1e-9 tolerance and truncates
+  them; Android rejects them. This is not a portable fractional interval feature.
+- Timed zero attack/release initially becomes one sample on Apple before duration
+  trimming; Android preserves zero. Matching validation does not establish
+  sample-identical envelopes.
+- Some early Apple rejections and unknown/retired Android sequence stops bypass
+  rejection counters. Recorded reason totals describe recorded failures, not
+  every rejected API call.
+- Sequence filter sweeps refresh every 16 samples on Android and every 8 on Apple.
+  Both use note length, but their PCM output is not guaranteed to match.
+
+Exact constraints and platform differences are in the [API](api.md) and
+[engine](audio-engine.md). Sound objects follow the same native source-compatibility rules.
+
+## Diagnose audio without overstating evidence
+
+Use the [statistics API](api.md#getstats) and [engine telemetry](audio-engine.md#engine-statistics).
+Keep unavailable readings as `null`, poll slowly, and cancel the owner's timer.
+Render load is callback work divided by its deadline, not whole-app CPU.
+Sample-peak ceilings do not certify speaker safety or inter-sample peaks.
+Start after layout settles; Android startup underruns, output routes, Bluetooth
+latency and sustained maximum load require their own device checks.
+
+The official [Sound validation record](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/sound-api-validation.md)
+separates validator, bridge, within-platform PCM, host allocation/GC and scoped
+physical evidence. Host dispatch timings are not Titanium bridge/device latency;
+byte-identical PCM comparisons are within each platform, not across platforms.
+Historical measurements retain their original revision and acceptance limits,
+including failed or inconclusive results. They do not certify every workload.
+Raw reports and reproduction tools remain in the native module repository
+for maintenance. You do not need those files to implement sounds.