Compatibility and Versioning

Compatibility and Versioning

This is the compatibility contract for reopening older FWG material. If you are only using current v3.0 exports with current v3.0, you can usually skip it.

Supported public contract

Fractured Wavetable Generator v3.0 emits schema 13 and explicitly imports public schema 12 and current schema 13.

The governing compatibility ethic is:

Minimal special accommodation for old ways of doing things.

A current FWG build tries to recover useful design intent from supported older files, but it is not an emulator for every historical executable. Exact historical reproduction belongs to the archived executable identified by the file's application version.

Current exports identify both the live application URL and the version-derived archive URL. The public archive is part of the reproducibility strategy rather than a reason to accumulate old DSP implementations in current code. A derived archive path can still be unavailable if that build was never published.

Scanning identities

Public v2.9c had no Scanning generators. v3.0 therefore introduces Scanning with its declarative recipe contract from the feature's first public appearance. Unreleased candidate display names are not a compatibility surface.

A full exported Morph/Explorer document that depends on a custom Scanning recipe embeds the required recipe definition. Standalone recipes use the current scanning_recipe / scanning_recipe_collection document kinds. See Scanning Recipes.

Current versus historical behaviour

Current code owns current correctness. In particular:

• a later DSP correction may intentionally render an old patch differently under current semantics;
• supported older JSON is imported best effort and can produce migration notices;
• an unsupported schema is rejected rather than guessed, and FWG supplies an archive URL when the stored application version is identifiable;
• exact historical PCM should be reproduced with the archived executable, not by asking the newest build to recreate an old bug or old intermediate representation;
• inexpensive recognition of an old public field name or encoding may remain when it helps express the old file's design in the current model.

This distinguishes migration from emulation.

Drawn migration and current authoring rules

v3.0 is the first public FWG release whose Drawn patch domain is 512 internal cycle samples.

Current schema-13 numeric Drawn follows these rules:

1. ordinary/local construction modes treat exactly 512 authored numeric values as the literal stage-1 Drawn geometry;
2. Fourier/Fourier-clip are deliberate global exceptions when used as resample_mode, so exact-512 Fourier input is analysed rather than bypassed;
3. optional stage-2 transform always consumes the canonical bounded 512-sample Float32 stage-1 waveform;
4. Haar and Walsh are transform-only; Fourier can be both a sparse construction mode and a transform;
5. optional normalise:true acts only on the final Drawn waveform and preserves DC by applying one uniform gain around zero;
6. the historical >512 non-wrapped linear reduction remains supported; when a transform/normalise pipeline is active, that dense source is first reduced to the canonical 512-sample stage-1 authority;
7. numeric-array format labels do not decide construction versus literal semantics.

Public v2.9c/schema-12 is different historical material. Its 256 Drawn samples represented one periodic sampled table, so v3 migrates them with cyclic linear 2× interpolation: every old sample survives exactly at an even destination index and inserted samples interpolate between periodic neighbours, including the seam.

Browser-decodable audio import is separate. It takes 512 evenly spaced sample positions over decoded duration rather than using a schema-13 mathematical construction recipe. See Drawn Waveform.

Stable current identities

Current schema/public field names, Wavetable Type IDs, Morph mode IDs, deterministic engine/model identities, and named-draw tuple framing remain explicit current contracts. Changing those identities requires a deliberate schema/model/version decision. That does not imply that every historical alias, internal RC helper, or old DSP formula must remain executable forever.

Hidden Wavetable Type identities

Several legacy Wavetable Type identities remain loadable so supported older JSON does not lose its declared type, even though these identities are intentionally absent from the ordinary menu. Their stable IDs are compatibility identities, not UI ordering promises.

Stable ID	Hidden type	Compatibility note
33	Phase Blur	Legacy smoothing/interference identity retained for import.
27	Warm Saturation	Legacy mild tanh saturation identity retained for import.
28	Triangle Fold	Legacy gentle fold identity retained for import.
11	Low-Bit XNOR	Legacy inverted low-bit XOR identity retained for import.
23	Primary A/B Blend	Legacy Primary-control blend identity retained for import.
18	Interleave 1	Legacy one-sample source interleave identity retained for import.
20	Average	Legacy balanced-average identity retained for import.

Archive routing

New JSON includes:

• the normal live FWG URL;
• a version-specific archived executable URL.

For older JSON that predates those fields, FWG can infer the conventional archive filename from application.version when possible. The version token must first match FWG's accepted version syntax, and any displayed URL must then match the FWG GitHub/GitHub-Pages allowlist. Imported arbitrary URLs are not rendered as trusted links. The early v2.0a filename anomaly is handled explicitly.

Repository history remains useful for source archaeology, while the archived executable is the practical route for exact historical behaviour.

Morph and DSP compatibility

The current Wavetable one-oscillator and Spectral / FFT morph implementations perform internal DC centring and peak normalisation before final export cleanup.

Removing or relocating those internal stages would intentionally alter many intermediate tables and rendered-audio hashes, even if JSON structure remained compatible. Such a change must be treated as a DSP/version change rather than a documentation correction.

START-mod-END now factors:

• Moving or Fixed primary mode;
• modulation family;
• one Depth value in the shared 1–256 domain;
• Source Rate.

Stable concrete mode identities remain available to rendering, JSON, and deterministic reconstruction.

Runtime identity and diagnostics

Ordinary FWG sidecars and Explorer recipes can include passive runtime_environment information useful for support/history. Imports ignore that block; it is not authentication, trusted timestamping or attestation. MPC format.json remains intentionally minimal.

Launching with Render Diagnostics enabled through the ?render_diagnostics=a URL query parameter adds optional support/troubleshooting evidence to rendered sidecars. Diagnostics do not change DSP, random decisions, naming or PCM. Because diagnostic JSON can be large, that mode also disables the ordinary JSON byte-size import guards while retaining normal schema/content validation.

Deterministic reconstruction

The named-draw core is defined by the exact tuple framing, UTF-8 serialisation, SHA-256 digest, first-32-bit big-endian extraction, and primitive mapping rules. “SHA-256” alone is not enough to reproduce an output.

The application version determines:

• which named paths a planner requests;
• how results are interpreted;
• which DSP implementation renders the patch.

The authoritative reconstruction route is:

1. use the version recorded in the JSON;
2. obtain the publicly archived executable or verify its uncompressed HTML hash;
3. supply the stored seed and effective settings;
4. regenerate and compare the result.

Executable identity

Public release records should include the SHA-256 hash of the exact uncompressed HTML bytes.

The .html.gz delivery file may have a different compressed hash if compressor headers or settings differ while still expanding to identical HTML. The uncompressed hash identifies the executable.

Current compatibility evidence

v3.0's supported public JSON boundary is:

• public v2.9c / schema 12;
• current v3.0 / schema 13.

Maintained compatibility evidence includes genuine public schema-12 imports, 0–256 → 1–512 window migration, historical Drawn migration, explicit current Forward/Reverse sidecar reconstruction, Explorer result/recipe restoration, and historical missing Phase-Coherent Mode restoring Off.

Development-only schema numbers and field names from unreleased builds are not public compatibility promises.

Table-Safety standby state remains transient runtime state rather than hidden persistent patch history. Continuous live endpoint edits — including pointer drawing — may retain one bounded previous-valid table; structural replacements, including whole-Drawn Copy/Reset/Clear/Undo/Import actions, clear it. Offline audition/render standbys remain bounded to the current traversal and are never serialized. Public table_safety counts/events describe final structural substitutions rather than double-counting internal helper failures.

Phase-Coherent Mode reconstruction boundary

Phase-Coherent Mode persists its explicit workspace setting, but Coherent Preview/live tracking history is not a hidden serialized patch identity. Full deterministic renders create the trajectory state they require from the captured render plan. See Phase-Coherent Mode.

Schema-13 Drawn vocabulary

The v3 schema-13 Drawn contract includes local construction modes (linear, parameterised steps, signed Power / symmetric Power, superellipse, and the Cardinal family), Fourier construction, the optional two-stage transform field, the Fourier/Haar/Walsh transform collection, and final normalise:true.

The shared transform selector language uses exact singleton N, coefficient inversion -N, open ranges :B / A:, inclusive A:B, and comma unions. Fourier's current real-waveform selector ceiling is 256; Haar uses bands 0…9; Walsh uses sequency 0…511.

These schema-13 meanings are frozen for v3.0 compatibility. Future incompatible additions should use a later schema rather than retroactively redefining schema 13.