@maccesar/titools 5.2.0 → 5.2.1

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

@@ -1,121 +1,109 @@
 # Maintaining the synthesis snapshot
 
-The eight official Markdown mirrors and raw statistics comparison are derived
-from the reviewed TiSynthEngine working tree based on the commit in
-[source-snapshot.json](source-snapshot.json). This snapshot includes uncommitted
-native statistics methods, tests and documentation. The commit identifies the
-base; it does not contain all reviewed content. `reviewed_worktree_sha256`
-records the reviewed dirty-state fingerprint, including tracked differences
-and untracked files. The checker verifies that fingerprint in addition to the
-individual source/mirror hashes. A match establishes fidelity to that source
-state; it does not establish that the source is correct, committed, published
-or installed in an app. A different dirty fingerprint requires a fresh review.
-Read the native contracts, command conversion and renderers when auditing
-behavior. The maintainer workflow is `titools-skill-auditor` in this repository.
+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.
+
+## 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` |
+
+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.
 
 ## Sources and permitted transformations
 
-`api.md`, `audio-engine.md`, `examples.md`, `guide.md`, `recommendations.md`,
-`sound-design.md`, `troubleshooting.md` and `stats-performance.md` mirror the
-corresponding upstream `documentation/` files. `stats-performance.json` preserves
-the complete raw trials without Markdown transformations. These nine assets
-each record a full-source SHA-256 and final mirror SHA-256. Markdown provenance
-headers identify the working tree, base commit and full-source hash.
-
-Only these transformations are currently declared:
-
-- A provenance header and generated `TOC-START`/`TOC-END` navigation.
-- The upstream demo link in `examples.md` is rebased to the last committed
-  `example/app.js` at the base commit. Its label explicitly distinguishes that
-  demo from the pending statistics example in the reviewed working tree; a
-  GitHub commit link cannot expose uncommitted changes. It requires access to
-  the official module repository; the runnable app is not bundled here.
-- `examples.md` and `sound-design.md` retain their TiTools links to
-  [curated recipes](recipes.md). These additions are recorded as reversible
-  `link_fixes`, with the complete original and mirrored Markdown fragments.
-
-For Markdown mirrors, the snapshot test removes the header and generated
-navigation, reverses those fragments, and checks the full original source hash.
-The raw JSON is checked byte for byte. Update the declared
-transformations when an intentional source-derived edit is reviewed; never
-regenerate hashes merely to conceal an unexplained difference.
+Eight official Markdown documents are mirrored into nine parts, including the
+ordered examples/advanced-examples split. 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
+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.
+
+The fidelity regression strips provenance/navigation, concatenates example parts, reverses declared transformations and compares the complete source hash. Raw records must remain byte-identical. Update transformations intentionally; never change hashes merely to hide unexplained source drift.
 
 ## Protected curated content
 
-[recipes.md](recipes.md) is a TiTools contribution, not an official mirror.
-Preserve its recipes, lifecycle patterns and navigation during synchronization.
-Check every native option and envelope against the current contract. The
-rhythm tests execute the Markdown examples and assert their intended note
-onsets, lengths and cancellation behavior; they do not render audio.
-
-Do not remove either official mirror's curated recipe link just because the
-upstream source has no equivalent. The snapshot records these intentional
-differences so preservation and source fidelity can both be checked.
-
-## Statistics scope and evidence
-
-The reviewed source adds `getStats()`, `resetStats()` and
-`setStatsEnabled(Boolean)` to the previous eight-method API. Detect support
-before using them with older 1.0.0 beta binaries; the version string alone does
-not identify the feature. Basic counters remain available without enabling
-diagnostics. Monotonic-clock render timing and signal measurements are optional
-and default off; missing/unmeasured fields stay `null`, distinct from measured
-zero. Android backend underrun, buffer and latency fields are independent of
-that diagnostics switch and remain best-effort. Poll at a modest rate and
-cancel polling with the owning screen/service.
-
-[stats-performance.md](stats-performance.md) and its
-[raw trials](stats-performance.json) document an Android native host comparison
-against the base engine, including variability and excluded costs. They do not
-run the iOS callback, JavaScript bridge or real device stream, and do not prove
-device CPU, battery, heat, latency or physical underrun behavior. Review the
-native statistics contract/publication and tests independently of the benchmark
-percentages; no zero-overhead or unchanged device-performance guarantee follows.
+[Retro recipes](recipes.md) and [interaction/instrument recipes](recipes-interaction.md) are TiTools contributions. Preserve their acoustic intent, lifecycle ownership and entry links when upstream docs change. Their native sequence examples keep the original millisecond onsets and total envelopes through separate `duration` and `length`; no JavaScript timer schedules notes. The repeated chord is now one centered native chord sequence; the separate one-off layered chord retains its per-voice stereo pans.
+
+Focused executable recipe tests inspect submitted intervals, envelope lengths, pitch and cancellation IDs. They do not render audio or measure native callback timing.
+
+## Current contract and acceptance boundaries
+
+`start` configures one engine, up to 32 shared voices and one to four preallocated sequence slots. `playSequence` is the only successive-sound scheduler and returns a positive ID or zero. Sequence edits, state queries and cancellation name that ID. Global `setTempo` governs beat timing and synchronized modulation; millisecond sequences retain fixed times. Finite playback is the default, and circular patterns explicitly opt into looping.
+
+Selective `music`, `effects`, `ui` and `ambience` categories feed one shared effect chain; an explicit per-voice send overrides category selection. Live spatial position, noise clock, low-pass cutoff and compatible continuous voice controls ramp over 10 ms while preserving history. Priorities protect higher-priority voices without reserved quotas. See the [API](api.md) for exact limits, source compatibility, return values and event delivery.
+
+The [performance review](performance-review.json) documents the accepted
+control-thread changes: partial sequence-bank preparation and removal of idle
+allocations/orphan held-position metadata. The Apple rendering bundle was
+rejected after a physical stereo regression, and production returned to the
+stable callback. Earlier candidate timings and fidelity checks remain evidence
+of that rejected candidate, not a promised Apple render speedup. Current matched
+Apple bypass measurements and actual hardware/rate/block-size scope are in the
+report; global performance acceptance remains open.
+
+Historical statistics, Studio/unified transport, physical/Frontier measurements
+and Android FIR8 correction reports keep their original artifact and acceptance
+boundaries. The short Android Sim80 headphone result had zero backend xruns and
+accepted listening; it does not close the distinct ten-minute maximum-load,
+bypass, memory and strict Frontier presentation criteria. Current evidence and
+rejected candidates must not be combined into a general pass. This skill update
+did not rerun devices, install binaries or alter native source.
+
+The 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:
+
+- iOS timed tone/chord command construction still rounds accepted zero attack
+  and release to at least one sample; Android preserves zero. Validator
+  acceptance does not establish identical sample envelopes.
+- iOS early tempo/sequence/processing rejections and incompatible held spatial/
+  modulation edits can bypass rejection counters. Android also leaves some
+  unknown/retired sequence-stop returns uncounted. The recorded reason sum is
+  consistent with recorded totals, not a complete API-call rejection tally.
+- Sequence cutoff coefficients currently refresh every 16 samples on Android
+  and every 8 samples on Apple; both use note length but do not promise identical
+  sample output. See [engine details](audio-engine.md).
+- 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.
+
+
+These findings are skill corrections and module implementation findings, not
+native 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.
 
 ## Upstream documents outside the mirror set
 
-The snapshot declares `documentation/index.md` and
-`documentation/third-party-notices.md` in `excluded_documents`, including each
-reviewed hash and reason. SKILL.md supplies the distributed navigation;
-dependency notices accompany the official module and native packages. This
-skill does not distribute Oboe, native binaries or KEMAR impulse responses.
-Changes or deletion of these excluded documents still require review. New
-upstream documents remain visible as new documents until reviewed and mapped
-or explicitly excluded; these records are not a blanket ignore rule.
+The official index is replaced by this skill's task routing. Dependency/license notices remain in the official module and binary packages. Both are recorded with hashes and reasons in `excluded_documents`, so changed or newly added documents still require review.
 
 ## Verification after a reviewed update
 
-```bash
-node scripts/verify-module-snapshot.mjs --skill ti-synthengine --source /path/to/TiSynthEngine
-node --test test/ti-synthengine.test.js test/ti-synthengine-recipes.test.js
+Run the focused mirror/link and recipe tests, then:
+
+```sh
+node scripts/verify-module-snapshot.mjs --source /path/to/TiSynthEngine --skill ti-synthengine
 ```
 
-Run these from TiTools. The checker is read-only: it reports source dirtiness,
-commit drift, source/mirror changes, missing files and new official documents.
-It never fetches, pulls or synchronizes. In the module checkout, also run the
-applicable official documentation, contract and DSP checks described in
-[audio-engine.md](audio-engine.md#regression-coverage).
-
-Regenerate navigation only after inspecting the generator's dry run. Refresh
-the snapshot's mirror hashes after navigation and declared additions are final.
-Before committing, inspect source differences and the distributed package;
-neither an old passing test count nor hash equality substitutes for that review.
-
-## Native findings and acceptance boundaries
-
-At the 2026-10-14 audit, iOS command construction converted zero attack/release
-to at least one sample; Android preserved zero. The shared envelope therefore
-has a one-sample boundary difference. This remains an upstream implementation
-finding: no native changes were made during the documentation correction.
-Recheck command construction or rendered output before calling it resolved.
-
-Java/iOS corpus parity covers validator acceptance/reasons, not rendered
-samples. The shared FIR suite and Android host tests establish narrower DSP
-properties. Inspect their current assertions for rate endpoints and exact
-tail-history coverage rather than assuming every advertised case is tested.
-The JavaScript rhythm checks interpret submitted options; they are not native
-scheduler timing measurements.
-
-Device startup/route behavior, iOS rendering, headphone localization, CPU,
-battery and underruns need their own evidence. Contract-valid recipes are not
-automatically pleasant or perceptually well localized.
+The verifier checks source/mirror hashes, exclusions, new documents, base HEAD and the exact tracked/untracked worktree fingerprint. Refresh that fingerprint only after the source changes are finished. No npm version, publication or native-device acceptance follows from this procedure.