feat(music): add INT8 quality preview

README.md

@@ -40,6 +40,8 @@ the downloaded model.
 
 The site uses ACE-Step 1.5 Turbo in direct mode. The optional planner is
 available in the underlying runtime but disabled on the public music page.
+Advanced settings includes a full-size, experimental INT8 quality preview for
+listening comparisons; it does not yet provide a smaller download.
 See the [ACE-Step README](packages/acestep/README.md) for implementation and
 validation details.
 

music.html

@@ -100,11 +100,9 @@ <h1>ACE-Step 1.5</h1>
               >Ace-Step 1.5</a
             > music generation model.
           </p>
-          <p>
-            The model is downloaded on first generation and cached for later visits.
-          </p>
-          <p id="download-note" class="download-note" hidden>
-            Total download size is <strong>5.75 GB</strong>
+          <p id="download-note" class="download-note">
+            The first generation downloads <strong>5.75 GB</strong>, then caches
+            the model for later visits.
           </p>
           <p
             id="support-warning"
@@ -217,6 +215,18 @@ <h1>ACE-Step 1.5</h1>
                   placeholder="e.g. English"
                 />
               </label>
+              <label class="model-variant-field">
+                Model
+                <select id="model-variant" name="model-variant">
+                  <option value="production" selected>Production (recommended)</option>
+                  <option value="int8-quality-preview">INT8 quality preview (experimental)</option>
+                </select>
+                <small>
+                  The preview tests audible quantization effects but is not compressed.
+                  It is also 5.75 GB; switching from a cached production model adds a
+                  separate 3.02 GB DiT download. Use the same seed to compare.
+                </small>
+              </label>
             </div>
           </div>
         </details>
@@ -274,6 +284,10 @@ <h2 id="progress-title">Preparing</h2>
               <dt>Generation time</dt>
               <dd id="summary-time">—</dd>
             </div>
+            <div>
+              <dt>Model</dt>
+              <dd id="summary-model">—</dd>
+            </div>
           </dl>
           <div class="result-actions">
             <button id="split-stems" class="split-stems-button" type="button">

packages/acestep/optimization/LEDGER.md

@@ -3,7 +3,7 @@
 Stage 2 was explicitly authorized on 2026-08-13. The approved baseline is
 frozen and measured optimization is active.
 
-Next available ID: `OPT-0090`.
+Next available ID: `OPT-0091`.
 
 | ID | Subsystem | Hypothesis | Evidence | Disposition | Result | Record | Implementation |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -96,6 +96,7 @@ Next available ID: `OPT-0090`.
 | OPT-0087 | Planner package-native dense GEMV | Route the already exact direct M1/M2 packed-BF16 kernel through all real planner decode layers and tied-head slices so the package can realize its useful bandwidth without OPT-0083's artificial submit-and-drain boundary around every isolated layer sample | positive | pending-integration | Actual Chrome preserved every full logit, appended K/V-cache evidence word, status, token, Philox cursor, topology, cancellation, and lifecycle result. Direct B won `16/16`, lowered every M1/M2 layer/head/model/complete median, reached `2.229363x` aggregate layer speedup, and reduced aggregate model-through-readback median `272.150 → 156.200 ms` (`115.950 ms`, projected `117.110 s/1,010`). Cleanup balanced `3,683/3,683` buffers and `133/133` maps with zero live resources. The fresh nominal launch passed; all later level-1/2 thermal observations are disclosed. Complete trajectory and planner-enabled product gates remain mandatory | [record](experiments/OPT-0087-planner-package-native-low-row-gemv.md), [result](results/OPT-0087/result.json) | allocation `84470d877ba69c6ef7821871f9bdb82d8c757747`; unchanged OPT-0083 direct kernel; implementation/harness `980623e0f9ec918f7a537b6a90e341adaad6d4b0`; pending integration gates |
 | OPT-0088 | Portable device support | Every subgroup-dependent production owner (OPT-0032/0037 dense K4, OPT-0051 K7 row-reuse, OPT-0048 ConvTranspose K4, attention query8/quad-query) can gain a workgroup-memory counterpart consuming the unchanged hosted packages, selected by the existing execution-profile machinery, so adapters without `subgroups` (Safari, Firefox, iOS) run the production graph instead of failing `FEATURE_UNAVAILABLE`; compatibility experiment, bounded slowdown expected and reported, `shader-f16` stays fail-closed | pending | pending-integration | Portable dense/K7/ConvTranspose owners landed with test-enforced bit-identical arithmetic (byte-equal WGSL arithmetic sections, re-exported rev7/rev8 index math); attention routes to the existing portable oracle (reordered-rounding vs subgroup reduction). End-to-end masked-subgroups waveform and timing gates pending | [record](experiments/OPT-0088-portable-no-subgroup-production-path.md) | kernels c272b2d/c48c050/373e90a; selection wiring pending |
 | OPT-0089 | DiT weight quantization | Weight-only symmetric int8 (per-32-K-block fp16 scales, round-to-nearest, clamp ±127) fake-quantization of all 264 rev7 DiT GEMM tensors, dequantized in place and run through the completely unchanged production graph, preserves end-to-end 30 s waveform quality within a small numerical envelope, so an int8-resident DiT (~1.51 GB + scales) is a credible answer to the observed iPhone 17 Safari OOM kill at `1,789,925,376 / 3,020,808,192` uploaded bytes (layer 14/24); pure quantization-damage gate, zero kernel changes, distinct mechanism from abandoned OPT-0058 activation-quantized DP4a | positive | benchmark-only | Per-tensor damage uniform and small: NRMSE `0.00515–0.00634` (median `0.00559`), min SNR `43.96 dB`, no outlier tensor/family, so no fp16-retention map needed. Determinism gate reproduced the pinned fp16 baseline WAV byte-exactly, then fake-quant vs fp16 on identical seeds gave lo-fi/12345 waveform NRMSE `0.0669` (Pearson `0.99777`, LSD ≈`3.5 dB`, RMS Δ `−0.050 dB`) and latin/424242 NRMSE `0.2268` (Pearson `0.97460`, LSD ≈`4.7 dB`, RMS Δ `+0.089 dB`; per-second max `5.19` is a near-silent-ending small-denominator artifact) — trajectory divergence of the 8-evaluation sampler, not noise-like corruption; zero non-finite samples and exact peak parity. Projected int8 DiT phase peak ≈`1.862 GB` tracked GPU (`1.51 GB` int8 + `94 MB` scales + fp16 norms/shared + measured `127 MB` overhead) versus the observed iPhone 17 kill at ≈`1.920 GB` — plausibly fits, marginal ≈`58 MB` margin; int8 kernel work justified, listening gate mandatory before any product claim | [record](experiments/OPT-0089-dit-int8-weight-fake-quant-gate.md), [quant result](results/OPT-0089/quant-error.json), [waveform result](results/OPT-0089/waveform-metrics.json) | `scripts/requantize-dit-int8.py` (repo root); fake-quant package `ef8355b9…` (models-local, not hosted); benchmark-only, no kernel or production change |
+| OPT-0090 | DiT quantization listening preview | The authenticated OPT-0089 fake-quant package can be exposed as an explicit opt-in listening comparison without changing the production default, weakening package identity checks, or claiming packed-int8 size/runtime benefits | positive | integrated | Reproduced the recorded `ef8355b9…` package and byte-identical quant report, published the immutable full-size artifact, then added an Advanced listening selector with orderly model switching and explicit size/non-production disclosure. 43 web integration, 4 unit, and 2,029 ACE tests plus typecheck, formatting, production build, and all PR checks passed; fresh browser/GPU listening remains external | [record](experiments/OPT-0090-int8-quality-preview.md) | implementation `2816d6b83185cbde5abd6780a9f5ac903a655154`; artifact `ac50b5c854fb044ce058acb91d4cd9ab82d99cfa` |
 
 Experiment IDs are allocated before code changes, never reused, and never
 removed from this table.

packages/acestep/optimization/experiments/OPT-0090-int8-quality-preview.md

@@ -0,0 +1,70 @@
+# OPT-0090 — INT8 quantization listening preview
+
+## Status
+
+- Evidence: `positive` (artifact and integration gates; external listening pending)
+- Disposition: `integrated`
+- Date: 2026-09-15
+- Risk class: `approximate`, opt-in only
+
+## Objective
+
+Expose the authenticated OPT-0089 fake-quant DiT as a public, opt-in listening
+comparison while keeping the owner-approved production model as the default.
+This preview evaluates audible quantization effects. It is not an int8-resident
+runtime and does not reduce download or GPU-resident bytes.
+
+## Trust and product boundaries
+
+- Reproduce the package from the pinned rev7 source with
+  `scripts/requantize-dit-int8.py`; require the recorded `ef8355b9…` manifest
+  identity and unchanged OPT-0089 quantization metrics.
+- Publish it under a distinct immutable path and authenticate every manifest and
+  payload through the existing content-addressed loader.
+- Retain the production package as the default after reload and in the SDK.
+- Label the preview experimental and full-size. Switching after production is
+  cached adds a separate 3.02 GB DiT package; shared main and VAE assets remain
+  reusable.
+- Do not claim packed-int8 size, memory, speed, mobile support, or approved
+  listening quality from this preview.
+
+## Gates
+
+1. Reproduction: source and output manifest hashes match OPT-0089; generated
+   quantization results match the committed report.
+2. Runtime: only the exact preview manifest is accepted with the unchanged
+   OPT-0009 layout/runtime profile. Any other identity fails closed.
+3. UI: production is the immutable default; model switching is disabled while
+   work is active and forces orderly worker/GPU disposal before reuse.
+4. Cache/progress: content-addressed assets coexist without deletion or identity
+   aliasing; cold-download wording describes the selected variant accurately.
+5. Validation: focused protocol/config/page tests, complete ACE package tests,
+   integration tests, formatting, and production build pass.
+6. Listening remains external: a public user may compare outputs, but promotion
+   to a default or packed-int8 runtime requires a separately recorded listening
+   decision and implementation gate.
+
+## Rollback
+
+Remove the opt-in UI/configuration and leave the production trust root
+unchanged. The unreferenced content-addressed preview package may then be
+removed from hosting.
+
+## Result
+
+- Reproduction produced the recorded manifest
+  `ef8355b9cffff466b018b51275923982b071234933fe8a32897915eeeb01fa36`;
+  the generated quantization report was byte-identical to OPT-0089
+  (`7bb7293a…`).
+- The full-size package is hosted under the immutable
+  `v1/dit-int8-fakequant/<manifest-sha>/` path in Hugging Face commit
+  `ac50b5c854fb044ce058acb91d4cd9ab82d99cfa`. The live manifest and one large
+  plus one small shard were downloaded again and matched their declared hashes.
+- Production remains the default. The Advanced selector is disabled with the
+  rest of the form during work, and switching variants disposes the previous
+  worker before initializing another.
+- Validation passed: 43 web integration tests, 4 unit tests, 2,029 ACE tests,
+  package and page typechecks, formatting, and the production build. No fresh
+  browser/GPU generation was available in this environment; OPT-0089 retains
+  the authenticated browser waveform evidence, while public listening is the
+  purpose of this preview.

packages/acestep/src/model/package.ts

@@ -36,7 +36,7 @@ export interface AceLoadPackageManifestOptions {
   readonly expectedProfile: AcePackageProfile;
   /** Exact revision-7 VAE trust root; rejected unless paired with its SHA. */
   readonly authenticatedVaeConverterRevision?: 7;
-  /** Exact OPT-0009 oracle only; rejected unless paired with its pinned SHA. */
+  /** Exact authenticated rev7 DiT trust roots; rejected for every other SHA. */
   readonly authenticatedDitDenseConverterRevision?: 7;
   readonly signal?: AbortSignal;
   readonly fetch?: typeof fetch;
@@ -80,12 +80,14 @@ export async function loadAcePackageManifest(
     options.authenticatedDitDenseConverterRevision !== undefined &&
     (options.authenticatedDitDenseConverterRevision !== 7 ||
       options.expectedProfile !== "fp16-dit-dense-experimental" ||
-      expectedDigest !==
-        "d3fc0020efcf60702db411da2fd4b93e9bb84f1437ed310aef01c892727e452f")
+      (expectedDigest !==
+          "d3fc0020efcf60702db411da2fd4b93e9bb84f1437ed310aef01c892727e452f" &&
+        expectedDigest !==
+          "ef8355b9cffff466b018b51275923982b071234933fe8a32897915eeeb01fa36"))
   ) {
     throw new AceModelTransportError(
       "MANIFEST_IDENTITY_ERROR",
-      "Legacy mixed-DiT parsing requires the exact authenticated OPT-0009 manifest",
+      "Legacy mixed-DiT parsing requires an exact authenticated rev7 manifest",
     );
   }
   const url = absoluteUrl(options.manifestUrl);

packages/acestep/src/runtime/protocol.ts

@@ -42,6 +42,7 @@ import {
   ACE_OPT_0056_DIT_SELECTIVE_K4_KERNEL_SET_ID,
   ACE_OPT_0056_DIT_SELECTIVE_K4_RUNTIME_PROFILE,
   ACE_OPT_0088_DIT_DENSE_PORTABLE_KERNEL_SET_ID,
+  ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256,
 } from "../webgpu/dit-fp16-package.js";
 import {
   ACE_OPT_0062_DIT_QUAD_QUERY_ATTENTION_KERNEL_SET_ID,
@@ -139,6 +140,12 @@ export type AceWorkerDitDensePackageConfiguration =
       readonly manifestSha256: typeof ACE_OPT_0009_DIT_DENSE_MANIFEST_SHA256;
       readonly runtimeProfile: typeof ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE;
     }>
+  | Readonly<{
+      readonly manifestUrl: string;
+      readonly manifestSha256:
+        typeof ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256;
+      readonly runtimeProfile: typeof ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE;
+    }>
   | Readonly<{
       readonly manifestUrl: string;
       readonly manifestSha256: typeof ACE_OPT_0037_DIT_K4_MANIFEST_SHA256;
@@ -501,7 +508,9 @@ function isWorkerDitDensePackageConfiguration(
       (value.runtimeProfile === ACE_OPT_0037_DIT_K4_RUNTIME_PROFILE ||
         value.runtimeProfile ===
           ACE_OPT_0056_DIT_SELECTIVE_K4_RUNTIME_PROFILE)) ||
-      (value.manifestSha256 === ACE_OPT_0009_DIT_DENSE_MANIFEST_SHA256 &&
+      ((value.manifestSha256 === ACE_OPT_0009_DIT_DENSE_MANIFEST_SHA256 ||
+        value.manifestSha256 ===
+          ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256) &&
         value.runtimeProfile === ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE))
   );
 }

packages/acestep/src/runtime/webgpu-pipeline.ts

@@ -166,10 +166,13 @@ import {
   ACE_OPT_0056_DIT_SELECTIVE_K4_KERNEL_SET_ID,
   ACE_OPT_0056_DIT_SELECTIVE_K4_RUNTIME_PROFILE,
   ACE_OPT_0088_DIT_DENSE_PORTABLE_KERNEL_SET_ID,
+  ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_BYTES,
+  ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256,
   createAceReferenceDitSharedManifestView,
   isAceReferenceDitLayerWeightFile,
   requireAceOpt0009DitDensePackageIdentity,
   requireAceOpt0037DitK4PackageIdentity,
+  requireAceOpt0089DitFakeQuantPackageIdentity,
 } from "../webgpu/dit-fp16-package.js";
 import {
   ACE_TURBO_EIGHT_SAMPLER_SCHEDULE_PROFILE,
@@ -3064,7 +3067,8 @@ export function createAceWebGpuPipelineBackend(
         manifestUrl: configuration.manifestUrl,
         expectedManifestSha256: configuration.manifestSha256,
         expectedProfile: "fp16-dit-dense-experimental",
-        ...(identity.role === "opt-0009-rev7-oracle"
+        ...(identity.role === "opt-0009-rev7-oracle" ||
+            identity.role === "opt-0089-rev7-fake-quant-preview"
           ? { authenticatedDitDenseConverterRevision: 7 as const }
           : {}),
         signal,
@@ -3398,6 +3402,20 @@ export type AceDitDensePackageRuntimeIdentity =
       readonly residentWeightBytes:
         typeof ACE_OPT_0009_DIT_MIXED_RESIDENT_WEIGHT_BYTES;
     }>
+  | Readonly<{
+      readonly role: "opt-0089-rev7-fake-quant-preview";
+      readonly manifestSha256:
+        typeof ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256;
+      readonly manifestByteLength:
+        typeof ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_BYTES;
+      readonly runtimeProfile: typeof ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE;
+      readonly kernelSetId:
+        | typeof ACE_OPT_0009_DIT_DENSE_KERNEL_SET_ID
+        | typeof ACE_OPT_0088_DIT_DENSE_PORTABLE_KERNEL_SET_ID;
+      readonly layerBytes: typeof ACE_OPT_0009_DIT_MIXED_LAYER_BYTES;
+      readonly residentWeightBytes:
+        typeof ACE_OPT_0009_DIT_MIXED_RESIDENT_WEIGHT_BYTES;
+    }>
   | Readonly<{
       readonly role: "opt-0037-rev8-production";
       readonly manifestSha256: typeof ACE_OPT_0037_DIT_K4_MANIFEST_SHA256;
@@ -3426,6 +3444,23 @@ export function resolveAceDitDensePackageRuntimeIdentity(
   configuration: AceWorkerDitDensePackageConfiguration,
   kernelBackend: AceKernelBackend = "subgroups",
 ): AceDitDensePackageRuntimeIdentity {
+  if (
+    configuration.manifestSha256 ===
+      ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256 &&
+    configuration.runtimeProfile === ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE
+  ) {
+    return Object.freeze({
+      role: "opt-0089-rev7-fake-quant-preview",
+      manifestSha256: ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_SHA256,
+      manifestByteLength: ACE_OPT_0089_DIT_FAKE_QUANT_MANIFEST_BYTES,
+      runtimeProfile: ACE_OPT_0009_DIT_DENSE_RUNTIME_PROFILE,
+      kernelSetId: kernelBackend === "portable"
+        ? ACE_OPT_0088_DIT_DENSE_PORTABLE_KERNEL_SET_ID
+        : ACE_OPT_0009_DIT_DENSE_KERNEL_SET_ID,
+      layerBytes: ACE_OPT_0009_DIT_MIXED_LAYER_BYTES,
+      residentWeightBytes: ACE_OPT_0009_DIT_MIXED_RESIDENT_WEIGHT_BYTES,
+    });
+  }
   if (
     configuration.manifestSha256 ===
       ACE_OPT_0009_DIT_DENSE_MANIFEST_SHA256 &&
@@ -3446,9 +3481,9 @@ export function resolveAceDitDensePackageRuntimeIdentity(
     });
   }
   if (kernelBackend === "portable") {
-    // Only the OPT-0009 oracle package has a portable kernel counterpart.
+    // Only rev7-layout packages have a portable kernel counterpart.
     throw new Error(
-      "ACE portable mixed DiT accepts only the OPT-0009 rev7 oracle package",
+      "ACE portable mixed DiT accepts only an authenticated rev7 package",
     );
   }
   if (
@@ -3747,6 +3782,8 @@ function requireLoadedDitDenseManifestIdentity(
   const identity = resolveAceDitDensePackageRuntimeIdentity(configuration);
   if (identity.role === "opt-0009-rev7-oracle") {
     requireAceOpt0009DitDensePackageIdentity(loaded);
+  } else if (identity.role === "opt-0089-rev7-fake-quant-preview") {
+    requireAceOpt0089DitFakeQuantPackageIdentity(loaded);
   } else {
     requireAceOpt0037DitK4PackageIdentity(loaded);
   }