@maccesar/titools 5.2.3 → 5.2.4

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

@@ -0,0 +1,283 @@
+> 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/native-variation.md` SHA-256: `30bbf837a163372aa0d369c6c8e267dc8fc2d3349e8ae30c51d13d20c88cb7eb`.
+
+# 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 local 1.1.0 packages, with public API version `1.0.0` and variation schema version `1`. The published 1.0.2 packages do not accept it. The local packages have not been published as a release.
+
+## Select the local package
+
+Install the matching locally built 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; the new property does not change the reported public API version.
+
+## 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 following examples 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 |
+| `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 |
+| `updateVoice({ 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 shot; keep the application's existing firing clock.
+
+```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.updateVoice({ voiceId: 71, volume: 0.12 })
+synth.noteOff({ voiceId: 71 })
+```
+
+`updateVoice` 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 promises selected parameters, not 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.updateVoice({ 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/433d7884800f70fb4803dbfe2e0e869cd5411889/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/recommendations.md

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree source based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/recommendations.md` SHA-256: `de212dae8b2b362c241cc2b63c7e11cad9db1ff758fd52ffba4fd26ac66bf794`.
+> 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/recommendations.md` SHA-256: `d3d508efe07fce012baceb44285aa9ab4b850cc5c53a5d14c9b8d193e38ca8fb`.
 
 # Recommendations
 
@@ -87,7 +87,7 @@ Do not copy the frequency maximum into application code. It depends on the activ
 
 The same rule applies to `noiseRate`, `lowPassHz` and `filterHz`. Validate a custom `waveTable` as 2 to 64 finite values from -1 to 1, and remember that `bitDepth` accepts zero or an integer from 2 to 16. For `detune`, check the resulting pitch too: a shifted pitch that leaves the frequency range is rejected even when the cents value is in range.
 
-Check Boolean return values during development. A rejected call includes the method, key and reason in the native log. Logging that result at the caller is often enough to identify a stale preset or misspelled field.
+Check each method's documented return value during development: Boolean publication acceptance or a positive sequence ID, with 0 rejecting a sequence. Methods that emit structured validation warnings include the method, key and reason in the native log, but some sequence/control rejection paths do not log. Logging the return at the caller helps identify a stale preset or misspelled field without treating silence in the native log as acceptance.
 
 ## Test the intended sound
 

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree based on commit `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/sound-design.md` SHA-256: `d7dbf023a72b2baaf726c20f6e240795f25095e63124264d8a13d9202b42e1d0`.
+> 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`.
 
 # Sound design with TiSynthEngine
 
@@ -6,6 +6,8 @@ TiSynthEngine generates sound with oscillators, without recorded samples. Pitch,
 
 Additional [curated recipes](recipes.md) provide application sound and interaction variants.
 
+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:
 
 ```javascript
@@ -137,27 +139,27 @@ synth.playTone({
 
 ## Envelope and total duration
 
-Every event uses an attack, an implicit sustain section and a release:
+A timed tone or chord uses an attack, an implicit sustain section and a release (with an optional decay stage described below):
 
 ```text
 silence -> attack -> full level -> release -> silence
           |<---------- duration ---------->|
 ```
 
-`duration` is the total time, not the sustain time. If duration is 500 ms, attack is 50 ms and release is 100 ms, the full-level middle lasts 350 ms.
+`duration` on `playTone` and `playChord` is the total time, not the sustain time. If duration is 500 ms, attack is 50 ms and release is 100 ms, the full-level middle lasts 350 ms. Held voices instead release on `noteOff`; native sequence steps use `duration` for the next-attack interval and `length` or gate for the note deadline. Their release can overlap later attacks. See [the playback contracts](instruments-and-effects.md#3-complete-sound-sequences-and-layered-effects).
 
 Short attacks feel immediate. A 0 or 1 ms attack can be useful for percussion, but an abrupt start at an unlucky phase can sound like a click. Values between 5 and 15 ms keep most game feedback crisp without a hard edge.
 
 Long attacks soften the onset. Use 100 to 500 ms for pads and slow warnings. Release controls how the sound leaves: 20 to 80 ms feels tight, while several hundred milliseconds leaves a tail.
 
-Explicit attack and release values must fit. These relationships are required:
+For timed tones and chords, explicit attack and release values must fit. These relationships are required:
 
 ```text
 attack < duration
 release <= duration - attack
 ```
 
-Defaults are adjusted internally if a very short duration leaves no room, but values supplied by the caller are never reshaped silently.
+Timed defaults are adjusted internally if a very short duration leaves no room; explicit values must pass validation. Native rendering has additional edge rules: held and sequence voices use at least 3 ms attack/release, while iOS timed conversion rounds an accepted zero attack/release to at least one sample and Android preserves zero. Validator acceptance does not establish identical sample envelopes.
 
 ## Decay and sustain
 
@@ -177,7 +179,7 @@ Practical starting regions:
 
 `sustain` below 1 needs a nonzero `decay`. Without one the level would jump instantly, which clicks, so the call is rejected with `sustain_without_decay`.
 
-The release scales the level the note has reached. If the release begins while the decay is still running, the note leaves smoothly from that point. The decay still has to fit: `attack` plus `decay` cannot exceed `duration`, and the 50 ms default attack counts. Set a short `attack` explicitly for a tight pluck.
+The release scales the level the note has reached. If the release begins while the decay is still running, the note leaves smoothly from that point. For timed tones and chords, the decay still has to fit: `attack` plus `decay` cannot exceed `duration`, and the 50 ms default attack counts. Set a short `attack` explicitly for a tight pluck.
 
 ## Pan and movement
 
@@ -241,7 +243,7 @@ Filters shape harmonics, so give them a source that has some: `SAWTOOTH`, `SQUAR
 
 `filterQ` is the resonance. The default 0.7071 is flat. Values from 2 to 4 add character, and above about 6 the filter whistles around the cutoff. A low-pass or high-pass boosts the cutoff region by about `filterQ`, so Q 10 is roughly 20 dB. Lower the event `volume` as Q goes up. The limiter catches peaks, but a resonance that keeps hitting it makes the whole mix pump. The band-pass keeps unity gain at its center for every Q and only narrows.
 
-`filterHzEnd` moves the cutoff over the whole event. The motion is exponential, so each second covers the same musical distance. Set it above `filterHz` to open the filter and below to close it. Zero disables the sweep.
+For timed tones and chords, `filterHzEnd` moves the cutoff over the whole event. A native sequence sweep instead uses the note length and holds its endpoint during release. The motion is exponential, so each second covers the same musical distance. Set it above `filterHz` to open the filter and below to close it. Zero disables the sweep.
 
 ```javascript
 synth.playTone({
@@ -636,12 +638,12 @@ The two additional voice LFOs move filter cutoff, square PWM or sine FM index us
 
 ## Native space and creative drive
 
-| Processor | What changes | Useful starting region |
-| --- | --- | --- |
-| Stereo chorus | A short interpolated delay with offset LFO phases adds width and movement. | Rate 0.3 to 0.8 Hz, depth 0.15 to 0.35, mix 0.08 to 0.2. |
-| Ping-pong delay | Alternating echoes create rhythmic or spatial repeats. | 180 to 350 ms or synced eighths, feedback 0.15 to 0.35, mix 0.08 to 0.18. |
-| Stereo reverb | Damped comb/allpass reflections create a diffuse decay. | Decay 0.8 to 1.8 seconds, damping 0.5 to 0.7, mix 0.08 to 0.18. |
-| Optional saturation | Soft waveshaping adds harmonics and changes attack/timbre. | Drive 1.2 to 1.6 with a small blend; compare at matched levels. |
+| Processor           | What changes                                                               | Useful starting region                                                    |
+| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Stereo chorus       | A short interpolated delay with offset LFO phases adds width and movement. | Rate 0.3 to 0.8 Hz, depth 0.15 to 0.35, mix 0.08 to 0.2.                  |
+| Ping-pong delay     | Alternating echoes create rhythmic or spatial repeats.                     | 180 to 350 ms or synced eighths, feedback 0.15 to 0.35, mix 0.08 to 0.18. |
+| Stereo reverb       | Damped comb/allpass reflections create a diffuse decay.                    | Decay 0.8 to 1.8 seconds, damping 0.5 to 0.7, mix 0.08 to 0.18.           |
+| Optional saturation | Soft waveshaping adds harmonics and changes attack/timbre.                 | Drive 1.2 to 1.6 with a small blend; compare at matched levels.           |
 
 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.
 

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

@@ -1,23 +1,17 @@
 # Maintaining the synthesis snapshot
 
-These references describe **TiSynthEngine module 1.0.2, public API 1.0.0**.
-The corrected official documentation is a reviewed working tree based on
-`4a45f21230ffc5a8838fbd5fc108dd3ab470362a`, recorded with its exact fingerprint in
-[source-snapshot.json](source-snapshot.json). The documentation corrections are
-not represented as committed by that base revision. Review date: 2026-10-29.
+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 replacement packages were freshly downloaded from the existing public URLs
-on 2026-10-30 UTC (2026-10-29 locally), rather than reusing cached 1.0.2 files.
+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 match the current GitHub asset SHA-256
-digests. These hashes replace the original 1.0.2 packages' hashes; filenames and
+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
@@ -32,15 +26,14 @@ app-root ZIP installation and both `tiapp.xml` declarations.
 
 ## Sources and permitted transformations
 
-Nine official Markdown documents are mirrored into ten parts, including the
-ordered examples/advanced-examples split. The current snapshot inventories all
+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 new [performance review](performance-review.json) and its raw archive are
+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 reviewed working-tree provenance header and recorded navigation transformations. Native-backed corrections to stale official prose are also declared as reversible `link_fixes`; the source hash still identifies the original official text, not the corrected mirror. 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.
+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.
 
@@ -82,11 +75,10 @@ fixed-gain recommendations target the measured 1–8-voice configuration, with
 underrun remains unresolved, including independent silent Oboe reproduction.
 Route-wide latency, Bluetooth and extended maximum-load acceptance remain open.
 
-Official corrections now preserve panic cancellation (`stopAll` stops every
+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. Their superseded mirror errata were removed;
-remaining native-backed errata and curated recipe navigation stay reversible.
+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.
@@ -110,12 +102,10 @@ 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 earlier native findings were independently rechecked against the
-1.0.2 source on October 29. These current differences remain explicit;
-hash fidelity alone cannot establish them:
+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 still rounds accepted zero attack
-  and release to at least one sample; Android preserves zero. Validator
+- 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
@@ -124,21 +114,23 @@ hash fidelity alone cannot establish them:
 - 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).
-- Android `getDefaults()` additionally returns `capabilities` and
-  `limits.stepDurationMs`; iOS omits those keys. Both platforms return
-  `limits.maxSequences`, `limits.priority` and `limits.effectSend`. Detect
-  required methods rather than requiring Android-only metadata flags. Sequence
-  intervals use different beat and millisecond ranges; see [API](api.md).
-- Remaining stale official claims are corrected only where verified against
-  current native behavior, with exact reversible transformations. Corrections
-  already adopted upstream are removed from the transformation list.
-
-
-These findings are skill corrections and module implementation findings, not
-native fixes. No module code, public range or hardware acceptance was changed.
+- 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. Consumer scenarios and exact native locators
-are recorded in the maintainer's October 23 audit evidence.
+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