@maccesar/titools 5.2.3 → 5.2.5

package/skills/ti-synthengine/references/native-variation-proposal.md

@@ -0,0 +1,182 @@
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/native-variation-proposal.md` SHA-256: `17b74434b0e03e5353b71c693d4ec722dede92fee8aed142003e67f60e158e27`.
+
+<a id="native-per-attack-variation--proposal-and-implementation-plan"></a>
+
+# Native per-attack variation: proposal and implementation plan
+
+Historical proposal, written on November 1, 2026 before implementation. The design and unchecked plan below record that starting point, not outstanding implementation work. Current source and local 1.1.0 candidates implement the feature; use the [implemented contract](native-variation.md) and [technical verification](native-variation-validation.md) for current behavior and acceptance. Writing the original proposal did not change native sources, binaries or packages.
+
+Implementation update (November 1, 2026): current source and local 1.1.0 candidates implement the contract on both platforms. See [the implemented contract](native-variation.md) and [verification](native-variation-validation.md). The proposal and historical feasibility findings below describe the starting point; they are not release announcements.
+
+## Purpose and ownership
+
+Generate subtly different versions of the **same** sound: an anvil struck at different places, not a different object on each hit. The Engine owns random selection once per new native voice. Apps supply an authored recipe, permitted ranges and amount. Studio exposes the controls and saves those choices; Frontier and Guardian use the same public property.
+
+The existing oscillator, anti-aliasing, ADSR, fixed event gain, chord compensation, routing, output protection and Oboe/Apple audio backends remain intact. This is an optional addition at voice creation, not a redesign of mixing or dynamics. A recipe without variation must preserve its existing output exactly. Do not revive the rejected Studio touch adapters, gesture delays, normalization or output-protector experiments.
+
+Studio's independent catalog expansion imports Playground, Frontier and Guardian sound examples. That work can ship independently. It does not implement random selection or require this future feature. The accepted pure-sine preset formerly named Cristal is now Seno puro (`clean`); preserve its approved sound.
+
+## Proposed public contract
+
+Use one optional dictionary named `variation` on `playTone`, `playChord`, `noteOn`, sequence `voice`, and step `overrides`. Unknown fields remain rejected by the closed contracts.
+
+```javascript
+synth.playTone({
+  frequency: 620,
+  waveType: WAVE.SINE,
+  duration: 180,
+  attack: 1, decay: 65, sustain: 0.12, release: 110,
+  fmRatio: 2.7, fmDepth: 3.2, fmDepthEnd: 0.4,
+  volume: 0.30,
+  variation: {
+    amount: 0.5,
+    // seed: 20261101, // Optional: deterministic comparison/testing.
+    ranges: {
+      volume: [0.291, 0.30],
+      fmDepth: [2.944, 3.456],
+      pitchCents: [-12, 12]
+    }
+  }
+});
+```
+
+- Omitted `variation`: current behavior, no extra RNG calls or changed noise state.
+- `amount`: finite number 0 to 1, default 1 when variation is supplied. Zero bypasses sampling and leaves authored values unchanged. The dictionary is still validated.
+- `ranges`: dictionary of permitted field ranges. Empty ranges have no audible effect. Each value is exactly two finite numbers `[minimum, maximum]` with minimum ≤ maximum. Equal endpoints deliberately fix a value when amount is 1.
+- `seed`: optional integer 0 to 4294967295. Zero is a valid deterministic seed, not the sentinel for automatic seeding. Omission uses the Engine's independent variation stream.
+- Non-pitch ranges are **absolute native parameter values**, not multipliers. Interpolate from the authored value toward the sampled value: `authored + amount * (sampled - authored)`.
+- `pitchCents` is a relative offset, initially zero. Multiply the already tuned/detuned frequency and its active sweep endpoint by `2 ** (amount * sampledCents / 1200)`.
+- Each range samples a uniform distribution. No quantized three-variant selection, hidden rounding to preset choices or automatic rejection of a natural repeated value.
+
+### Version-one fields
+
+| Range field  | Bounds and compatibility                                               | Identity rule                                                                                |
+| ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `volume`     | Current native event volume 0 to 2                                     | Sample before existing fixed chord compensation; no other voice is rescaled.                 |
+| `filterHz`   | 20 to active frequency ceiling; an enabled resonant filter is required | Changes starting cutoff; the authored `filterHzEnd` remains the same endpoint.               |
+| `filterQ`    | 0.5 to 10; enabled resonant filter required                            | Does not change filter type.                                                                 |
+| `fmDepth`    | 0 to 10; SINE only                                                     | Does not change `fmRatio`; an authored FM endpoint, including zero, remains unchanged.       |
+| `noiseRate`  | Positive colored-noise range accepted by current API; NOISE only       | Does not change waveform; authored noise sweep endpoint stays fixed.                         |
+| `lowPassHz`  | Enabled cutoff, 20 to active ceiling                                   | Does not randomly switch the low-pass on/off. A disabled low-pass cannot receive this range. |
+| `pulseWidth` | 0.05 to 0.95; SQUARE only                                              | Does not change waveform; authored PWM endpoint stays fixed.                                 |
+| `pitchCents` | −1200…1200, intentional opt-in                                         | Preserve both the starting pitch and pitch-sweep trajectory under the same multiplier.       |
+
+Native validators must use the actual existing source/range rules rather than assuming all numeric intervals are continuous. In particular, do not interpolate through an invalid bypass/cutoff gap. Pitch corners must remain within the active frequency ceiling, including an existing detune and every frequency in a chord/step. Reject a dictionary whose reachable extremes are invalid; never silently clamp the variation to conceal an invalid recipe.
+
+Version one deliberately keeps waveform, wavetable, quantization, FM ratio, filter type, ADSR, event duration, rhythmic interval, routing and priority authored. This preserves the principal sound shape and simplifies timed-envelope correctness. Optional duration/ADSR variation is a separate future design: it must not randomly violate envelope budgets or move a sequence's rhythmic grid. The earlier discussion of varying 140 to 170 ms was an illustration, not a shipped promise.
+
+### Attacks, held notes, chords and sequences
+
+1. **Timed tone / held note:** sample once as the new voice starts. Reuse the sampled values throughout sustain and release. Playing another note, lifting another finger or repainting UI must not resample this voice.
+2. **Chord:** validate the complete call before admission. Each admitted voice gets its own deterministic draws, then the existing compensation applies. Keep atomic chord admission and existing pan/detune behavior.
+3. **Sequence:** sample when each scheduled voice actually starts in the native transport, not when JavaScript submits the score. Every new iteration gets new draws. Rests consume none. This is the main advantage over baking variations in JS step overrides.
+4. **Inheritance:** a step without `variation` inherits the prepared root voice. A step with `variation` replaces that whole dictionary. `{amount:0}` disables it for that step; partial nested merge semantics are intentionally avoided.
+5. **Updates:** `updateVoice` does not accept this attack-only dictionary. Explicit live edits retain their normal smoothing and set the requested fields without resampling other fields or restarting the envelope. `updateSequence` may change ranges/amount for future attacks; active voices keep their sampled state.
+6. **Seed stream:** a seeded tone/note call begins at attack index zero, so repeating exactly that call reproduces it. A seeded chord uses note ordinal as a further index. A seeded sequence owns an attack counter that continues across loops and normal revisions. Stop/new play restarts the seeded stream; changing the seed restarts it when the new revision applies. Re-publishing the same seed must not accidentally reset it.
+
+## Deterministic and realtime design
+
+Implement one small C-compatible shared helper, provisionally `shared/synth_variation.h`, used by both platform renderers. Use an integer-defined generator/hash with golden vectors, stable field slots and explicitly defined conversion to a uniform scalar. A counter-based `(seed, attack index, chord voice ordinal, field slot)` scheme avoids dependence on JavaScript property order and on adding another optional field. Review statistical quality against this sound-design use; this is not a cryptographic RNG.
+
+Maintain a separate random stream/counter from oscillator noise. Enabling variation in another voice must not change an existing noise waveform. Omitted/zero amount consumes no variation draws and does not disturb legacy noise state. Seed automatic streams at control/start time, never by calling an OS entropy service in the audio callback.
+
+Parse/validate dictionaries and prepare numeric fixed-size configuration on the producer/control side. At an attack, native code uses bounded constant-time arithmetic and preallocated storage. No allocation, locks, sleeps, collection creation, JSON, JS calls, OS RNG or logging in the callback. No per-sample randomization of these parameters. Existing LFO and sweep processing continues normally after the attack.
+
+Inspect actual packet and bank sizes before choosing storage. `SynthSequenceVoice` is copied into up to 512 steps, three prepared banks and four transports; adding a dictionary-sized object or copying large tables for variation would be wasteful. Use a bit mask plus fixed numeric fields, and measure the resulting worst-case memory instead of guessing.
+
+## Verified implementation seams to inspect
+
+- `android/src/ti/synthengine/SynthContract.java`: closed timed/held/chord validation, including `validateNoteOn`.
+- `android/src/ti/synthengine/SynthStudioContract.java`: sequence voice/override validation and prepared packet encoding.
+- `android/src/ti/synthengine/SynthThread.java` and `TiSynthEngineModule.java`: command preparation, bridge/default metadata.
+- `android/jni/SynthOboeEngine.cpp`: `Voice`, command-to-voice setup, sequence attack creation and JNI packet decoding.
+- `ios/Classes/TiSynthengineContract.{h,m}`: equivalent validation and prepared sequence/command structures.
+- `ios/Classes/TiSynthengineModule.m`: `startVoiceFromCommand`, sequence-created voices and defaults/capabilities.
+- `shared/synth_sequence.h`: `SynthSequenceVoice`, `SynthSequenceStep`, prepared banks and attack events.
+- `shared/synth_held.h`, `synth_modulation.h`, `synth_core.h`: preserve held envelope, modulation and oscillator contracts.
+- Existing `tests/engine_render_host.cpp`, platform contract regression tests and actual Apple callback host tooling: extend their relevant cases rather than inventing a second renderer.
+
+The graph was used to identify these seams. It reports partial indexing of `synth_sequence.h`; exact source is authoritative. Confirm concrete entry-point signatures against the current checkout before editing.
+
+## Range authoring policy
+
+A preset should define a small subset of the eight fields, with most fields left alone. Musical instruments preserve tuning by default. Mechanical/game impacts may opt into small pitch changes. Amount 100% means the full **authored subtle range**, not an uncontrolled maximum across the API.
+
+Starting references from the archived Frontier experiment:
+
+- Impacts/destruction: pitch multiplier 0.95 to 1.05, about −88.8…84.5 cents. Shots: 0.97 to 1.03, about −52.7…51.2 cents. These are optional FX bounds, not instrument defaults.
+- Colored-noise rate/cutoff: 88 to 112% of the anchor; FM depth 92 to 108%; Q 95 to 105%.
+- Event level: 97 to 100% of anchor, deliberately never louder than that anchor.
+- ADSR/timing/voice count remain unchanged.
+
+Convert these references into absolute native ranges in each recipe. Do not bake those percentages as mandatory Engine defaults: the Engine must not guess what an anvil, glass or trumpet means. Technical range validity and recognizability are distinct; audition the material at low, midpoint and full amount.
+
+<a id="feasibility-and-compatibility-review--november-1-2026"></a>
+
+## Feasibility and compatibility review: November 1, 2026
+
+The proposed opt-in feature is feasible. It requires changes to both validators, bridge packets, command preparation and the voice-start paths, including sequence attacks. No implementation or performance acceptance is claimed by this review.
+
+### Compatibility requirements and consumer impact
+
+| Consumer scenario                                                   | Required behavior                                                                                                                                                                                      |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| An installed app keeps its existing module package                  | Nothing changes; the module is bundled with that app.                                                                                                                                                  |
+| An app rebuilds with the new package but never supplies `variation` | Existing recipe parameters, admission, envelopes, gains, processing and noise algorithm/state progression remain unchanged. No variation draws occur.                                                  |
+| An app supplies valid `{amount:0}`                                  | Validate the dictionary, then take the same rendering path as the unvaried recipe.                                                                                                                     |
+| An app explicitly supplies active ranges                            | Only new attacks sample the permitted fields. Existing sustained voices are not resampled.                                                                                                             |
+| A newer app runs with an older package                              | Omit the entire `variation` key unless feature support is advertised. Old closed validators reject unknown keys, including an amount-zero dictionary. Do not retry an unsupported recipe indefinitely. |
+
+Package version and reported API compatibility are separate concerns. Playground's `Resources/lib/synthSafe.js` requires `apiVersion === '1.0.0'`; Guardian's audio system also compares its expected API version exactly. Changing that string would make those apps reject the module or fall back even if every existing sound call remained valid. Studio's inspected source does not impose that exact-version check; Frontier's inspected app/Resources source contains no `apiVersion` check.
+
+**Recommendation, not a published contract:** retain the existing compatibility identifier for unchanged core methods and advertise this optional extension explicitly on both platforms, for example `capabilities.variation: true` plus `variationSchemaVersion: 1`. Publish a new module package version when implementation is ready; do not replace the 1.0.2 release. If the API identifier instead changes, prepare the affected consumer checks before claiming drop-in compatibility. Current iOS metadata omits Android's capability map, so adding the variation flag must be implemented on iOS too.
+
+Apps that do not opt in need no recipe edits. Opting in requires the new package and a support check. Studio additionally needs saved range/amount fields, schema migration, validation, serialization to every supported playback path and explicit controls. Frontier/Guardian need material-specific ranges attached to their recipes; visual variant selection remains a separate concern. No shared recipe registry or reusable sound-object API is required.
+
+### Native details that the implementation must preserve
+
+1. **Validate the effective step voice.** Root voice and step overrides already merge before validation. Validate inherited ranges against each effective waveform/filter and every effective pitch. A step that changes from sine to noise cannot silently discard inherited FM variation: replace the variation dictionary or explicitly disable it for that step. A variation-only `updateSequence` edit must not reset its seed counter or touch active voices.
+2. **Apply samples before all derived state.** Android held starts initialize `SynthLive` and may inherit compatible release-tail phase/filter state. Sequence sweeps also read a retained `sequenceShape`. Sample before building those derived values, and retain the sampled starting shape and pitch-scaled endpoint. Sampling only the initial volume/filter/frequency would allow the next live/sweep update to overwrite it. Apply the equivalent rule on iOS.
+3. **Define admission and draw order.** Use a fixed-width attack counter and stable field slots. Advance an event counter only after that attack is admitted; rejected events and rests consume no draws. All notes in an admitted chord share that event index and use their note ordinal for independent draws. Automatic streams must distinguish successive one-shot calls. Explicitly seeded one-shot calls restart at index zero, so repeating the same seeded call intentionally repeats its sampled parameters. Specify counter wrap in the shared helper.
+4. **Do not confuse parameter determinism with noise PCM.** An explicit variation seed reproduces selected parameter values. Existing oscillator noise is separate: Android currently seeds a voice from its address/sample index; iOS uses time/slot state. A variation seed does not promise identical noise samples, complete PCM or cross-platform output. Compare absent/zero variation against the old renderer using the same controlled noise initialization in the test harness; preserve production noise behavior. Do not change the noise generator to make this test pass.
+5. **Preserve waveform meaning.** Pitch variation is useful for tuned sources; ordinary oscillator pitch does not transpose a NOISE source. Author noise effects with clock/filter variation. Keep waveform, ADSR, duration, timing, routing, priority and FM ratio outside V1, as already specified. In particular, authoring FM ranges from an initially zero depth must still satisfy the effective FM-ratio/source rules.
+6. **Measure storage and callback cost.** A 64-bit macOS host `sizeof` probe of the unchanged header measured `SynthSequenceVoice=824`, `SynthSequenceStep=1400`, one config `718,920` and one triple-bank transport `2,156,928` bytes. Four such transports total `8,627,712` bytes, excluding renderer voices, command queues and other state. A naive candidate containing amount, sixteen double endpoints, mask and seed flags is 152 bytes; adding it to every step of every bank of four transports would add 933,888 bytes before other copies. These are baseline/layout measurements, not an implemented storage design or a device benchmark. Prefer a compact representation and consider sharing repeated effective configurations within an immutable prepared bank if measurement justifies it.
+
+### Acceptance before consumer rollout
+
+The compatibility claim is a release gate, not a conclusion established by this proposal. Tests must cover omitted and amount-zero variation through timed tones, chords, held notes and native sequences on both platforms, including existing profiles, release overlap and deterministic noise fixtures. Assert unchanged authored configs, stable sustained voices, no extra noise-state consumption, atomic chord admission, unchanged gain compensation, correct sweep starts/endpoints and newly sampled loop attacks. Measure dense publication memory and callback load; retain physical listening as a separate acceptance step.
+
+The review ran only source inspection and the isolated host layout probe. No renderer, bridge, package, existing app sound or physical device was changed.
+
+## Implementation plan and gates
+
+- [ ] **Contract first:** add paired Android/iOS rejection/acceptance tests for omitted, zero, minimum/midpoint/maximum amount, unknown keys, malformed/inverted/nonfinite ranges, incompatible sources, bypass gaps, invalid seeds and pitch corners. Watch new-feature tests fail before adding support.
+- [ ] **Shared sampling helper:** implement fixed-size config and deterministic math; test golden vectors, field ordering, seed zero, repeatability, independence from noise RNG, bounded outputs and no mutation of authored configurations.
+- [ ] **Both renderers in one work cycle:** add strict bridge/prepared fields, initialize them on every path and sample at actual voice creation, including native sequence retriggers. Review timed/chord/held/sequence paths separately. No platform-only completion.
+- [ ] **Native behavior tests:** compare absent/zero-variation PCM to the prior renderer for every waveform/profile/path with controlled identical noise initialization in the harness; use representative fixed seeds to compare platform selections and rendered outcomes. Confirm held notes stay stable when unrelated voices start/release; confirm eight/32-note chords and looping sequence attacks advance the stream correctly.
+- [ ] **Lifecycle and edits:** stop/panic/restart, failed admission, voice stealing, capacity saturation, stale sequence revisions, seed changes, 512 steps/four transports, varying override source types, updates while a note sustains. Verify no partially admitted chord and no stale uninitialized variation mask.
+- [ ] **Performance/memory:** measure callback work for 1/8/16/32 voices and four active sequences, max bank memory and publication allocation behavior. Absent/disabled paths must remain effectively unchanged. Never reinterpret a host benchmark as physical latency/listening acceptance.
+- [ ] **Metadata/docs/example:** advertise support on both platforms in `getDefaults()` capabilities/limits, document fields/defaults/seed/loop behavior and add a clear example. Review exact API-version checks in consumer apps before selecting the feature's development/API version. Do not silently publish 1.0.2 binaries with an undocumented new contract.
+- [ ] **Consumer integration:** once the native packages exist, Studio forwards the property from its switch/amount/preset bounds; Frontier and Guardian supply their ranges. Remove app-side samplers, preserve visual variant selection, stable IDs and saved edits. The catalog remains usable when the optional native property is absent.
+- [ ] **Physical acceptance:** same-anvil identity, non-repeating nearby strikes, tuned instrument chords, stable held notes, complete finite effects, fresh sequence-loop variations and representative headphones/speakers on Android/iOS. Record listening separately from validator/PCM evidence.
+
+Do not broaden to the entire module suite automatically. Start with the new shared helper and affected contract/render tests. Broaden when a shared struct/packet change makes existing serialization/lifecycle regressions relevant, and explain that concrete reason. Run release-required checks only if an actual release is requested.
+
+## References and workspace state at proposal time
+
+- Current base: TiSynthEngine 1.0.2 packages, public API 1.0.0. Engine checkout was `main` ahead of `origin/main` by one preexisting documentation commit before this proposal; do not discard it.
+- Engine mixing/output/oscillator fixes are valued by César. He initially froze the Engine during the unrelated Cristal investigation, then authorized this specific optional variation feature and requested the proposal in the Engine repository.
+- Native implementation is **not started** by this document. No release, tag, force push, consumer installation or physical-device operation is authorized merely by the plan.
+- Complete Studio JS prototype (archived, removed from production): `/Users/cesar/Developer/validation-evidence/TiSynthEngine/native-variation-proposal-2026-11-01/studio-prototype/README.md`.
+- Complete Frontier JS prototype/range tests (archived, removed from production): `/Users/cesar/Developer/validation-evidence/TiSynthEngine/native-variation-proposal-2026-11-01/frontier-prototype/README.md`.
+- Frontier prototype proved 271 zero-amount recipe results identical to HEAD and exercised 162 generator/action cases ×32 seeds. Studio prototype checked per-attack ownership and sampled-sequence limitations. These are reference experiments, **not native implementation evidence**. They sampled some fields differently from the proposed native V1 contract; do not copy them wholesale.
+- Studio ongoing catalog: `/Users/cesar/Developer/Apps/TiSynth-Studio/documentation/sound-library.json`; generator `tools/import-sound-examples.js`. Source files are snapshotted at development time; the shipped app must not require sibling source projects.
+
+### Historical implementation request
+
+> Read AGENTS.md, docs/project/status.md and documentation/native-variation-proposal.md. Implement the optional native per-attack variation contract on Android and iOS, preserving absent/disabled behavior and existing DSP/mixing. Start with the scoped tests and verify the sequence-loop/held-note/seed guarantees. Treat the document as a proposal whose contradictions should be resolved explicitly; do not publish a release or install on devices without the corresponding instruction. Integrate consumer controls after the native contract and packages are verified.
+
+
+## Deferred API-model question (separate scope)
+
+César raised whether a recipe should be a registered reusable sound object with a method such as `clickSeco.play()`, instead of a reusable options dictionary submitted on every call. He explicitly asked to defer this observation and continue the current catalog/proposal work. Record it for a later API-design discussion; it is not authorization to add a sound registry, cache or another playback wrapper to this feature. Do not expand native variation into a preset-object lifecycle project.

package/skills/ti-synthengine/references/native-variation-validation.md

@@ -0,0 +1,63 @@
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/native-variation-validation.md` SHA-256: `df18826824984cb440d7412b547663ba6b8a7152bc347508114d7af982c90e68`.
+
+# Native variation: technical verification
+
+Initial host and build verification on November 1, 2026, against Engine base `5a328ad`. Native sources build local 1.1.0 Android/iOS candidates; public API remains 1.0.0. The measurements below describe that technical stage. Later consumer installation and listening observations are recorded separately in the [follow-up](#consumer-installation-and-listening-follow-up); they do not turn the host measurements into physical-device benchmarks. No 1.1.0 release is announced by this report.
+
+## Contract and rendering
+
+- Shared C helper: a known SplitMix64 vector, independent attack/ordinal/field coordinates, bounded sampling, repeatability, no mutation of authored configuration, amount-zero bypass and schema-slot independence.
+- The paired corpus plus nonfinite probes exercises 156 cases on each production validator: tones, chords, held starts, sequence voices/overrides, source restrictions, malformed/inverted ranges, booleans, seeds including zero/uint32 maximum, amount endpoints, tuning/detune/chord/sweep pitch corners and zero-depth FM starts. `updateVoice` rejects variation.
+- Actual Android renderer and extracted actual Apple callback hosts cover deterministic parameters, held stability, independent chord ordinals, loop attacks, rests, rejected admission, revision continuity and changed seeds. A focused shared regression reproduced the structural-edit counter reset before its fix, then verified inherited-rest insertion, explicit root-seed change, appended explicit step seed zero and reordered declarations.
+- Absent/amount-zero PCM matches within the new renderer across six waveforms, four mixing profiles, held/chord/sequence paths and release. Noise initialization is controlled by existing host fixtures; production noise generation is unchanged.
+- Android's pre-feature and candidate `engine_render` fixture output, including its PCM hashes, matches exactly.
+- Apple pre-feature versus candidate PCM is byte-identical across the original 120 lifecycle/effects/transport scenarios: 29,692,526 bytes. The comparator's `--pcm-only` mode excludes internal structure snapshots because prepared sequence layouts intentionally changed.
+- An additional Apple compatibility driver compares the pre-feature renderer against both candidate absent and amount-zero modes across six waveforms, four profiles and four paths (timed, held, chord, native sequence), including overlap/release: 2,359,296 bytes match exactly in each comparison.
+- Existing native renderer, sequence-publication, retrigger, bypass, startup, contract and canonical-state memory checks accompany the focused variation cases. Existing tests with handcrafted packets now use the new internal header/step widths; the public score format is unchanged.
+
+Commands: `python3 tests/run_variation_contracts.py`, the two `variation_*_regression.c` executables, `python3 tests/run_native_hosts.py variation_engine`, and `python3 tools/build_ios_render_host.py --output /tmp/variation-ios --driver tests/variation_render_ios.m`. The compatibility driver is `tests/variation_compatibility_ios.m`, built once against the Git base extracted to an external temporary directory and once against the candidate. No checkout/HEAD changes are needed.
+
+## Storage and callback work
+
+64-bit macOS layouts:
+
+| Structure              | Base bytes | Candidate bytes |
+| ---------------------- | ---------: | --------------: |
+| Sequence voice         |        824 |             968 |
+| Sequence step          |      1,400 |           1,544 |
+| Prepared configuration |    718,920 |         794,704 |
+| Triple-bank transport  |  2,156,928 |       2,384,288 |
+| Four transports        |  8,627,712 |       9,537,152 |
+
+The four-bank-owner total grows by 909,440 bytes, including prepared explicit-seed identities. This excludes renderer voices/tails, command queues, effect rings, bridge arrays and canonical Java/Objective-C options. A variation configuration itself is 144 bytes. No dictionary or variable-size object reaches the callback. Explicit step seed declarations are sorted during preparation; application compares prepared root identity and seed declarations without sorting or allocation.
+
+The callback measurements below run four native transports at 48 kHz, 256 frames/block, 1,000 warmup and 1,000 measured blocks. Voice counts are distributed over the four transports; unused transports contain rests. Full-amount three-field variation is selected per admitted attack. Measurements are thread CPU time divided by rendered block budget, on the macOS hosts, without opening audio hardware.
+
+| Target voices | Android variation off | Android variation on | Apple variation off | Apple variation on |
+| ------------- | --------------------: | -------------------: | ------------------: | -----------------: |
+| 1             |                 0.49% |                0.41% |               0.48% |              0.50% |
+| 8             |                 1.43% |                1.41% |               1.85% |              1.78% |
+| 16            |                 3.01% |                2.59% |               3.07% |              3.08% |
+| 32            |                 6.48% |                4.80% |               5.53% |              6.04% |
+
+Run-to-run/cache/scheduling variation is visible; these single samples do not estimate a causal speedup or physical overhead bound. Other app builds were running during parts of this session. Wall time is retained in the external logs, separately from thread CPU time. At 32 voices, enabled mean CPU work is approximately 0.256 ms/Android callback and 0.322 ms/Apple callback on this host, with a 5.333 ms block budget.
+
+A 512-step publication check (100 edits, 32 pitches/step) measured Android JNI/native producer CPU p95 0.335 ms and Apple Foundation producer CPU p95 10.609 ms. These execute outside the audio callback and exclude Android Java preparation. The canonical Java memory regression verifies detached input, immutable reuse, rejected-edit isolation and release of accepted bridge packets. None of these results represents phone memory pressure, thermal stability, underruns or latency.
+
+## Packages and consumer acceptance
+
+Both module builds passed with `ti build -p android/ios --build-only`. Native-build archive SHA-256 before the final documentation-only refresh (the external packaging proof records the refreshed archives and proves native binary members unchanged):
+
+- Android: `4fc5cb31ecb16a0d3d8acc9599f87f71e322778f92073fa0042e49b24fcfbacb`.
+- iOS: `71b28d2473a7b56d7e966addad636037b985c1eb5bffa9f8a2e0737efe3ce2b7`.
+
+Consumer source tests, installed candidate-file parity and platform build evidence are recorded in each app's validation/session notes. The official 1.0.2 directories/archives are retained. Capability-gated fallback and authored range gains are tested independently from listening. Studio's personal presets, A/B, disabled/zero paths, layer ownership and pattern restoration have their own tests; module validation does not replace those checks.
+
+Technical hosts establish parameter/transport/rendering behavior within their stated scope. Physical real-time acceptance and comparative listening at low/mid/full amount remain separate and require free authorized devices.
+
+
+## Consumer installation and listening follow-up
+
+The current Studio, Frontier and Guardian builds using module 1.1.0 were installed over the existing apps on the OPPO CPH2639 and physical iPad (9th generation), preserving app data. Signed physical iOS builds succeeded with the projects' selected SDKs; these device builds do not require the missing simulator runtime.
+
+César reported that Studio's variations and control edits sound good, and specifically accepted Frontier's Órbita Neón / Roca Frágil variation. The device and output route were not specified in that feedback. This records those observations without extending them to all effects, both platforms or sustained maximum-load performance.

package/skills/ti-synthengine/references/native-variation.md

@@ -0,0 +1,285 @@
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/native-variation.md` SHA-256: `650d2c675dc4b4e09a85521812b7fedd3b02cb993a451378a8082e2b7782303a`.
+
+# Native per-attack variation
+
+`variation` lets the engine choose bounded parameter values when it admits an attack. Repeated shots can have different pitch, noise color or filter settings without JavaScript randomization. Each voice keeps the chosen values for its lifetime; existing envelopes, sweeps and LFOs continue from that starting configuration.
+
+Android and iOS support this dictionary in the 1.1.0 packages, with public API version `1.1.0` and variation schema version `1`. The published 1.0.2 packages do not accept it.
+
+## Select version 1.1.0
+
+Install the matching Android and iOS 1.1.0 archives in the app and select them in `tiapp.xml`:
+
+```xml
+<modules>
+  <module platform="android" version="1.1.0">ti.synthengine</module>
+  <module platform="iphone" version="1.1.0">ti.synthengine</module>
+</modules>
+```
+
+Rebuild and reinstall the application after replacing native modules. Copying module files alone does not update an installed app. Keep the published 1.0.2 archives separate; version 1.1.0 reports API `1.1.0`.
+
+## Detect support and start playback
+
+Check both metadata fields. API version alone does not identify variation support. Omit the property completely when either announcement is missing, including when the requested amount is zero.
+
+```javascript
+var synth = require('ti.synthengine')
+var contract = synth.getDefaults()
+var supportsVariation = !!(contract.capabilities
+  && contract.capabilities.variation === true
+  && contract.variationSchemaVersion === 1)
+var W = contract.waveTypes
+
+synth.start({ maxVoices: 8, maxSequences: 1 })
+synth.setVolume({ volume: 0.6 })
+```
+
+The examples below use those variables. Handle rejected publications through the normal [return values and diagnostics](api.md#return-values). For rapid effects, size the shared voice pool for overlapping durations and releases.
+
+## Supported locations
+
+| Call or score field                                | Behavior                                                                                         |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `playTone({ variation, ... })`                     | Chooses once for an admitted timed tone                                                          |
+| `repeatTone({ variation, intervalMs, ... })`       | Retains a stream/counter and chooses once per admitted repeated finite attack                    |
+| `updateTone({ toneId, variation, ... })`           | Replaces the whole future-attack dictionary; amount zero disables; seed change resets the stream |
+| `playChord({ variation, ... })`                    | Admits the whole chord atomically and chooses independent values for each voice                  |
+| `noteOn({ variation, ... })`                       | Chooses at the held voice's attack; sustain and release keep that configuration                  |
+| `playSequence({ voice: { variation, ... }, ... })` | Supplies the default for sounding steps on every native loop                                     |
+| `steps[i].overrides.variation`                     | Replaces the entire dictionary inherited from the sequence voice                                 |
+| `updateSequence({ voice, steps, ... })`            | Changes future attacks when the revision applies                                                 |
+| `updateNote({ variation, ... })`                   | Rejected; live edits must name the parameters they change                                        |
+
+Schema 1 varies `volume`, `filterHz`, `filterQ`, `fmDepth`, `noiseRate`, `lowPassHz`, `pulseWidth` and `pitchCents`. Waveform, table contents, ADSR, duration, cadence, FM ratio, routing, priority and voice count retain their authored values.
+
+## Dictionary reference
+
+```javascript
+var variation = {
+  amount: 0.5,
+  seed: 42,
+  ranges: {
+    volume: [0.20, 0.30],
+    pitchCents: [-24, 24]
+  }
+}
+```
+
+| Field    | Default                                 | Accepted values                                                         |
+| -------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| `amount` | `1`                                     | Finite number from `0` to `1`                                           |
+| `seed`   | Omitted; engine selects a native stream | Integer from `0` to `4294967295`; `0` is an explicit deterministic seed |
+| `ranges` | Empty dictionary                        | Any subset of the eight range names below                               |
+
+Only these keys are accepted. A range must contain exactly two finite numbers in ascending order. Equal endpoints are valid. Strings, booleans, `null`, `NaN`, infinity, reversed bounds and unknown names are rejected. An empty range dictionary makes no parameter changes and consumes no variation event.
+
+The frequency ceiling is the active engine's `limits.frequency.max` value from `getDefaults()`. The maximum is `sampleRate * 0.45`, with a 19,845 Hz fallback before startup. Read `getDefaults()` again after `start()` when preparing device-specific ranges.
+
+| Range        | Inclusive validation bounds             | Required source or setting                                                              |
+| ------------ | --------------------------------------- | --------------------------------------------------------------------------------------- |
+| `volume`     | `0` to `2`                              | Any source; existing chord compensation follows selection                               |
+| `filterHz`   | `20` Hz to the active frequency ceiling | Enabled resonant filter: `lowpass`, `highpass` or `bandpass`                            |
+| `filterQ`    | `0.5` to `10`                           | Enabled resonant filter                                                                 |
+| `fmDepth`    | `0` to `10`                             | `SINE`, with the normal FM ratio/depth rules                                            |
+| `noiseRate`  | `1` Hz to the active frequency ceiling  | `NOISE` with authored `noiseRate >= 1`                                                  |
+| `lowPassHz`  | `20` Hz to the active frequency ceiling | One-pole low-pass already enabled with authored `lowPassHz >= 20`                       |
+| `pulseWidth` | `0.05` to `0.95`                        | `SQUARE`                                                                                |
+| `pitchCents` | `-1200` to `1200` cents                 | Resulting tuned frequencies and active pitch endpoints must remain within engine limits |
+
+`filterHz` controls the resonant filter; `lowPassHz` controls the separate one-pole low-pass. A range cannot enable a bypassed filter or turn white noise into colored noise. Pitch cents change oscillator pitch; use `noiseRate` to change a noise source's clock. A zero-depth sine can start with an active FM-depth range when the remaining FM configuration is valid.
+
+## What amount means
+
+The engine samples each named range uniformly, independently of JavaScript property order. For absolute parameters:
+
+```text
+selected = authored + amount * (sampled - authored)
+```
+
+For example, with authored `filterHz: 1000` and range `[600, 1400]`, amount `0.25` permits 900 to 1100 Hz; amount `0.5` permits 800 to 1200 Hz; amount `1` uses the full range. Amount describes deviation from the authored value. A range may sit entirely above or below that value, in which case the deviation is biased in that direction.
+
+Pitch uses a multiplicative ratio after tuning and detune:
+
+```text
+ratio = 2 ** (amount * sampledCents / 1200)
+selectedFrequency = tunedFrequency * ratio
+```
+
+The same pitch ratio applies to an active `frequencyEnd`, preserving the sweep's interval. Other range names change their starting value while the corresponding authored sweep endpoint stays fixed. For example, varying `noiseRate` does not rewrite `noiseRateEnd`.
+
+Omitting `variation` or using a valid dictionary with `amount: 0` preserves the authored recipe and consumes no variation event. Both still obey normal noise initialization; a noise waveform can differ between attacks without this feature. Equal range endpoints force that selected field to their common value at amount `1`.
+
+Validation checks the complete reachable configuration before admission, including every chord or step pitch, tuning, detune and active sweep endpoint. Invalid dictionaries are rejected even at amount zero. The engine does not clip invalid bounds into an acceptable recipe.
+
+## Repeated independent effects
+
+Leave out `seed` to obtain successive native selections. Call `playTone` for each actual gameplay event. For periodic repetition of that finite recipe, call `repeatTone` with `intervalMs` once and retain its `toneId`; the renderer then owns the repeated deadlines. Standalone calls, including intentionally timed finite bursts, remain supported and return Boolean acceptance. `updateTone` changes future attacks, preserving the current deadline and variation counter. A changed seed restarts the stream, and dropped attacks consume no selection.
+
+```javascript
+function fireLaser() {
+  var tone = {
+    frequency: 900, frequencyEnd: 180,
+    waveType: W.SQUARE, pulseWidth: 0.35,
+    duration: 180, attack: 2, decay: 40, sustain: 0.25,
+    release: 90, volume: 0.22
+  }
+  if (supportsVariation) tone.variation = {
+    amount: 0.6,
+    ranges: { pulseWidth: [0.25, 0.45], pitchCents: [-36, 36] }
+  }
+  return synth.playTone(tone)
+}
+fireLaser()
+```
+
+The engine samples after admission and before initializing filters, smoothing controls and trajectories. Rejected attacks do not consume a selection. Existing release tails, capacity policy and voice replacement still apply.
+
+## Chords and application gain
+
+One chord is one atomic publication. Each voice uses its position within that attack to obtain independent field samples; it does not reuse the first voice's result. If the chord cannot be admitted, none of its voices starts and no event is consumed.
+
+Scale a volume range with the same application gain as the authored volume. Let the engine apply its existing chord compensation once.
+
+```javascript
+var gain = 0.7
+var chord = {
+  notes: ['C4', 'E4', 'G4'], waveType: W.TRIANGLE,
+  duration: 500, attack: 4, release: 120,
+  volume: 0.30 * gain
+}
+if (supportsVariation) chord.variation = {
+  ranges: {
+    volume: [0.24 * gain, 0.30 * gain],
+    pitchCents: [-8, 8]
+  }
+}
+synth.playChord(chord)
+```
+
+If an effect consists of separate layers, prepare each layer's ranges and gain independently. Variation does not change how many layers or voices the effect needs.
+
+## Sustained voices and explicit live edits
+
+A held voice samples once. Moving a slider, releasing another note or revising a sequence does not resample it. A live edit explicitly replaces its named parameter through the existing smoothing behavior.
+
+```javascript
+var held = {
+  voiceId: 71, frequency: 220, waveType: W.SINE,
+  attack: 12, release: 180, volume: 0.18,
+  fmRatio: 2, fmDepth: 1.4
+}
+if (supportsVariation) held.variation = {
+  ranges: { fmDepth: [1.1, 1.7], pitchCents: [-10, 10] }
+}
+synth.noteOn(held)
+synth.updateNote({ voiceId: 71, volume: 0.12 })
+synth.noteOff({ voiceId: 71 })
+```
+
+`updateNote` rejects `variation`. To obtain another varied attack, release the owned voice and start another through the normal ownership path. A sustained motor stays steady under a single held attack. Release owned IDs on cancellation, pause and teardown; keep the usual bounded handling of rejected releases.
+
+## Native loops and dictionary inheritance
+
+The transport selects at sounding attacks on every native loop, including independent samples for chord voices. Rests and attacks rejected by capacity consume none. Native loop variation does not need a JavaScript timer or a loop-finished callback.
+
+A step without `overrides.variation` inherits the root dictionary. Supplying that field replaces the whole dictionary, including its amount, ranges and seed declaration. It does not merge individual ranges. A step can therefore opt out with `{ amount: 0 }` or replace pitch variation with a filter-only dictionary.
+
+```javascript
+var voice = {
+  waveType: W.SINE, attack: 2, decay: 70,
+  sustain: 0.2, release: 80, volume: 0.16,
+  fmRatio: 2, fmDepth: 1.4
+}
+var steps = [
+  { notes: [60, 67] },
+  { rest: true },
+  { notes: [64] }
+]
+if (supportsVariation) {
+  voice.variation = {
+    seed: 20261101,
+    ranges: { fmDepth: [1.1, 1.7], pitchCents: [-12, 12] }
+  }
+  steps[2].overrides = { variation: { amount: 0 } }
+}
+var sequenceId = synth.playSequence({
+  timeUnit: 'beats', stepDuration: 0.25, loop: true,
+  voice: voice, steps: steps
+})
+```
+
+A revision changes future attacks when it applies. Existing voices retain their selected values. Supply the complete replacement dictionary, including a seed you intend to retain:
+
+```javascript
+if (supportsVariation && sequenceId > 0) {
+  synth.updateSequence({
+    sequenceId: sequenceId,
+    voice: { variation: {
+      seed: 20261101, amount: 0.5,
+      ranges: { fmDepth: [1.1, 1.7], pitchCents: [-12, 12] }
+    } }
+  })
+}
+```
+
+The root voice merges with the existing sequence voice on revision. Omitting `variation` from an updated root does not remove a dictionary already stored there. To clear it for future inherited attacks, publish an amount-zero replacement. Explicit step dictionaries still take precedence; revise those steps as well when disabling the whole score.
+
+```javascript
+if (supportsVariation && sequenceId > 0) {
+  synth.updateSequence({
+    sequenceId: sequenceId,
+    voice: { variation: { amount: 0 } }
+  })
+}
+```
+
+Stop the owned sequence through the normal lifecycle when it is no longer needed. Stop/new play starts a new stream.
+
+## Seeds and reproducibility
+
+| Usage                                                            | Reproducibility                                                           |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Repeated standalone calls with the same recipe and explicit seed | Reproduce the selected parameter values, starting at event zero each time |
+| Standalone calls without a seed                                  | Use successive native selections                                          |
+| Seeded native loop                                               | Advances its attack counter across loop iterations                        |
+| Revision with unchanged seed identity                            | Retains that counter                                                      |
+| Revision that changes the root seed                              | Resets the counter when the revision applies                              |
+| Stop followed by a new sequence                                  | Starts a new counter                                                      |
+
+Seed identity includes whether the root seed was declared and its value, plus the sorted multiset of explicit step seed declarations. Moving steps, swapping existing declarations or inserting inherited rests preserves that identity. Adding, removing or changing an explicit step seed declaration changes it and resets the counter. Prefer a root seed for comparisons of a complete score.
+
+The counter is an unsigned 64-bit value and wraps modulo `2^64`. Admitted attack, voice ordinal and field slot determine each sample through the shared integer helper. Field slots are stable, so changing dictionary property order or adding an unrelated range does not shift existing field samples. Variation state is separate from the noise generator. A reproducible seed reproduces selected parameters. It does not promise identical noise PCM or identical DSP output across platforms.
+
+## Rejected configurations
+
+These examples are intentionally invalid when variation is supported:
+
+```javascript
+// NOISE is required for a noiseRate range.
+synth.playTone({ waveType: W.SINE,
+  variation: { ranges: { noiseRate: [1000, 2000] } } })
+
+// Zero amount still validates the inverted range.
+synth.playTone({ variation: {
+  amount: 0, ranges: { volume: [0.4, 0.2] }
+} })
+
+// Live updates do not accept an attack-only dictionary.
+synth.updateNote({ voiceId: 71,
+  variation: { ranges: { pitchCents: [-10, 10] } } })
+```
+
+Also check pitch corners near 1 Hz or the reported ceiling. A valid base pitch can become invalid when its tuning, detune and maximum pitch offset combine. Keep module diagnostics when a recipe is rejected; a `false` return can also mean unavailable engine state or a full command queue.
+
+## Studio and game integration
+
+Studio calls this control Variantes. Its displayed percentage maps linearly: 25% sends native amount `0.25`, 50% sends `0.5`, and 100% sends `1`. Studio prepares broader ranges for its editor. The games retain their authored range profiles.
+
+Frontier automatically applies authored ranges only to its eligible destruction sounds; Guardian applies them only to its two lasers. Both require the capability/schema pair and keep their existing recipes on older modules. Studio allows any source to opt in through compatible parameter ranges. See [Studio's control and preset guide](https://github.com/macCesar/TiSynth-Studio/blob/main/documentation/variation.md); the native contract in this document does not depend on a consumer app.
+
+## Implementation and verification
+
+Both renderers use [`shared/synth_variation.h`](https://github.com/macCesar/TiSynthEngine/blob/7cd035409453b01df2736aef56f2316d94ca019c/shared/synth_variation.h): stable schema slots, integer-defined SplitMix64 finalization and exact uint32-to-uniform conversion. Parsing prepares a fixed 144-byte configuration outside the audio callback. The callback performs bounded arithmetic without allocation, locks, JavaScript calls or entropy services.
+
+Focused checks cover known vectors, both native validators, attack admission, chord ordinals, sustained stability, loops, revisions, rejection and old-renderer compatibility with controlled noise initialization. [Technical verification](native-variation-validation.md) records the measured memory/callback cost and its limits. Host results do not certify physical latency or listening quality on every device.

package/skills/ti-synthengine/references/recipes-interaction.md

@@ -337,7 +337,9 @@ This repeated chord uses one centered native sequence. The one-off layered chord
 
 ### Cancellable repetition
 
-Every repeating sound has an identified native owner. Repeated start requests coalesce until the matching retirement event frees its slot. Stop its sequence ID and cancel pending restarts when its window closes; no JavaScript timer schedules subsequent notes.
+The chord pulse above has an identified sequence owner. Repeated start requests coalesce until its matching `sequenceend` retirement frees the slot. Stop its sequence ID and cancel pending restarts when its window closes; its native sequence schedules subsequent chord attacks.
+
+For repetition of an original finite tone in API 1.1.0, use `repeatTone({ intervalMs, ...recipe })`, retain its positive tone ID, edit future attacks with `updateTone`, and cancel with `stopTone`. Each independent layer retains its own tone ID and overlap budget. `stopTone` preserves admitted finite attacks; `stopSequence` releases its sequence's voices. Tone IDs have no completion event, so the sequence retirement/restart procedure above does not apply to them. Independent event calls and intentionally timed finite JavaScript bursts remain supported; cancel any app-owned timers at teardown. See [the repetition contract](api.md#finite-tone-repetition) and [complete effect fidelity](instruments-and-effects.md#repeated-firing-uses-the-native-clock).
 
 ```javascript
 function cleanupAudio () {

package/skills/ti-synthengine/references/recipes.md

@@ -1,7 +1,8 @@
 # Curated sound and interaction recipes
 
-These recipes are tuned starting points for `ti.synthengine` 1.0.0. They use
-only public option keys, keep every explicit envelope valid, and obtain
+These recipes use the core public contract shared by `ti.synthengine`
+1.0.2 / API 1.0.0 and 1.1.0 / API 1.1.0. They use only public option keys,
+keep every explicit envelope valid, and obtain
 waveforms from the runtime contract instead of hardcoding integers. Install the
 matching official Android/iOS packages and follow the owning-engine
 [installation and lifecycle guide](guide.md) before using them.