@maccesar/titools 5.2.2 → 5.2.4

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.0 documentation at release source commit `e7cbbe8a6f9ab38088fd8029c7b43cef6501101f` (2026-10-24). Upstream `documentation/sound-design.md` SHA-256: `dd543e07c825aaf67a0a5f85619088a8d02721a9d33dbf4579edf760dad3e262`.
+> 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({
@@ -319,7 +321,7 @@ Choose the profile once in `start()`:
 | `speakerSafe`  | Lower source gain and a 0.70 ceiling for small speakers.          |
 | `raw`          | Full source gain; useful only when the app owns all gain staging. |
 
-Protected profiles calibrate source gain by waveform and event voice count. The final stereo-linked limiter catches exceptional peaks with 10 ms of lookahead and a 100 ms release. Its ceiling is 0.85, or 0.70 for `speakerSafe`.
+Protected profiles calibrate source gain by waveform and event voice count. The final stereo-linked sample protector applies immediate reduction with no retained samples and a 100 ms exponential recovery. Overload changes the waveform; fixed per-event gain and chord compensation remain unchanged. Its ceiling is 0.85, or 0.70 for `speakerSafe`.
 
 The limiter protects against peaks. If it engages on every note, lower event volume or choose a more conservative profile instead of using it to raise loudness. Repeatedly starting the same long sound before its previous release ends raises and lowers the sum, which can produce audible pumping. That overlap is useful as a stress test, but it is a poor reference for the tone's normal quality.
 
@@ -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,38 +1,39 @@
 # Maintaining the synthesis snapshot
 
-These references mirror the **public TiSynthEngine 1.0.0 release** at
-`e7cbbe8a6f9ab38088fd8029c7b43cef6501101f`, recorded in
-[source-snapshot.json](source-snapshot.json). The clean local checkout and remote
-main matched that commit on 2026-10-24. The repository is public; the Android
-and iOS releases are published, neither draft nor prerelease. Module availability
-is independent of publishing a new TiTools version.
+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
 
-| Platform | Published release | Package SHA-256 |
-| --- | --- | --- |
-| Android | [android-1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.0) | `cf3510f290eca6dd00e8e0742a7db4f09dd2b8c4ef9270ed1f34d30eb32389cf` |
-| iOS / Mac Catalyst | [ios-1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.0) | `bc2e3f88c2945df721dd2196dfbb852c64aa98954b04460adf56ca41c75e6e91` |
+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.
 
-Both platform tags and `v1.0.0` point at the reviewed commit; only the two
-platform tags have GitHub release pages. Downloaded ZIPs were independently
-hashed and inspected: module ID `ti.synthengine`, version `1.0.0`, minimum
-Titanium `13.2.0.GA`; Android includes four ABIs and the Apple manifest enables
-Mac Catalyst. See the [guide](guide.md) for Android API35 and iOS15 requirements,
-app-root ZIP installation and both `tiapp.xml` declarations. These checks do not
-constitute a fresh device installation or audio acceptance run.
+| Platform | Published release | Replacement package SHA-256 |
+| --- | --- | --- |
+| Android | [android-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2) | `8698104f188782a77699fbd6308a779ca0b190833ceebf398557b628af1b8bbe` |
+| iOS / Mac Catalyst | [ios-1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2) | `779e77d018d5b3f686d69cb1b4b0162281803ea12691487df565c1fd15175c58` |
+
+Both ZIPs passed full CRC checks and matched the GitHub asset SHA-256 digests at that verification. These hashes replace the original 1.0.2 packages' hashes; filenames and
+release URLs did not change. Manifests report module `ti.synthengine`, version
+`1.0.2`, minimum Titanium `13.2.0.GA`, four Android ABIs and Apple Mac Catalyst
+support. The manifest's native `apiversion` field is distinct from the JavaScript
+contract's `apiVersion: '1.0.0'`, which remains unchanged.
+
+All eight Android native libraries (inside the AAR) and three Apple static
+libraries match the preserved original 1.0.2 release packages byte for byte.
+Corrected guide, example and platform README HTML was inspected in both new
+packages. Source/package checks do not constitute a fresh device installation or
+listening acceptance. See the [guide](guide.md) for API35/iOS15 requirements,
+app-root ZIP installation and both `tiapp.xml` declarations.
 
 ## Sources and permitted transformations
 
-Eight official Markdown documents are mirrored into nine 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 local-commit 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.
 
@@ -48,6 +49,42 @@ Focused executable recipe tests inspect submitted intervals, envelope lengths, p
 
 Selective `music`, `effects`, `ui` and `ambience` categories feed one shared effect chain; an explicit per-voice send overrides category selection. Live spatial position, noise clock, low-pass cutoff and compatible continuous voice controls ramp over 10 ms while preserving history. Priorities protect higher-priority voices without reserved quotas. See the [API](api.md) for exact limits, source compatibility, return values and event delivery.
 
+### Module 1.0.1 and 1.0.2 corrections
+
+Michael Gangolf's [Android PR #1](https://github.com/macCesar/TiSynthEngine/pull/1)
+updates Oboe to 1.11.0, recovers closed streams after all stream errors, keeps a
+single demand-driven sequence-event poll chain and shuts down on root activity
+destruction. Removing the unused Java Thread inheritance changes no public API.
+The subsequent Apple correction polls only while sequence events or held-voice
+metadata need retirement and guards shutdown/restart reentry. Neither poller is
+a musical scheduler; explicit engine ownership/teardown remains required.
+
+Module 1.0.2 shares final output processing in `shared/synth_output.h`: zero
+retained samples, immediate stereo-linked sample protection, ceilings 0.85/0.70,
+100 ms exponential recovery and reset after two consecutive quiet stereo frames.
+Master volume ramps linearly over 10 ms on both platforms, independently of the
+protector. The iOS `raw` startup correction now applies its documented gain;
+existing raw mixes need review. Overload changes the waveform, and sample
+ceilings do not certify inter-sample peaks or speaker behavior.
+
+[Pipeline validation](audio-pipeline-validation.md) preserves the new production
+callback/CI checks, five-rate output comparisons and physical scope. Preset
+calibration measures both renderers and six scenarios at 1/2/4/8/16/32 voices;
+fixed-gain recommendations target the measured 1–8-voice configuration, with
+16/32 kept as stress diagnostics. It never edits Studio. The Android startup
+underrun remains unresolved, including independent silent Oboe reproduction.
+Route-wide latency, Bluetooth and extended maximum-load acceptance remain open.
+
+Official documentation corrections preserve panic cancellation (`stopAll` stops every
+sequence and invalidates effect histories), compatible live `updateVoice`
+noise/low-pass/spatial/send edits, and category selection with `applyTo` plus
+explicit `effectSend` overrides. The matching mirror-only errata were removed from the transformation list; curated recipe navigation remains reversible.
+Android and Apple production callback tests now run in CI; the historical Java
+DSP model is not the production audio oracle. No native binaries were installed
+or device/listening tests rerun during this skill update.
+
+### Historical evidence
+
 The [performance review](performance-review.json) documents the accepted
 control-thread changes: partial sequence-bank preparation and removal of idle
 allocations/orphan held-position metadata. The Apple rendering bundle was
@@ -65,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 October 23 native findings were independently rechecked against the
-published source on October 24. 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
@@ -79,20 +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()` includes capabilities and additional limit metadata
-  that the current iOS dictionary omits. Both expose the corresponding APIs;
-  detect 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.
+- 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 findings are skill corrections and module implementation findings, not
-native fixes. No module code, public range or hardware acceptance was changed.
+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