BarScript: serve the fitted (non-uniform) bar timeline by default; report grid source, spread and fit quality in the UI

README.md

@@ -71,10 +71,31 @@ package's contract. A Hub snapshot is additionally verified against the
 BarScript is under evaluation and has known defects. The interface lists all of
 them verbatim from the model card when the option is selected, including a
 non-nested difficulty ladder, over-dense output, and a uniform `/16` deployment
-lattice on which triplets are arithmetically impossible. It decodes onto a bar
-lattice built from the fitted BPM and first downbeat, and refuses to generate
-without one rather than anchoring the bars on an arbitrary phase. It takes no
-song plan, so the Structure and AI planner switches do not reach it.
+lattice on which triplets are arithmetically impossible. It takes no song plan,
+so the Structure and AI planner switches do not reach it.
+
+BarScript decodes onto a supplied bar timeline and refuses to generate without a
+downbeat rather than anchoring the bars on an arbitrary phase. When the beat fit
+passes its own quality gate, that timeline is the fitted barlines themselves —
+unevenly spaced when the fit found a tempo change — and every note position and
+every `#BPMCHANGE` in the exported TJA is derived from those bar edges. When the
+fit misses the gate the bars are tiled from a single BPM instead and no tempo
+change can be represented. The result says which of the two happened, with the
+fit's inlier fraction and RMS, the number of distinct bar lengths served, and any
+repair applied; a fallback is never silent.
+
+How often the barlines are right is a separate question from whether they *can*
+be uneven, and the answer is not good yet. Over 60 held-out songs (30 that change
+tempo per the authored trace, 30 that do not), 16 were served a non-uniform grid
+and only 8 of those actually change tempo — the verdict is a coin flip at this
+sample size. Nine of the 16 span a factor of ≥ 1.9 between their longest and
+shortest bar, the signature of a barline the estimator split in two rather than
+of a tempo change. The interface therefore reports the spread as a measurement
+and states that the two cases are not told apart, instead of announcing that a
+tempo change was captured.
+
+Per-bar **time signature** is a different matter again: nothing here estimates
+meter from audio, so one estimated time signature covers the whole song.
 
 `python spaces/scripts/test_app_wiring.py` checks the routing, the resolution
 order above, the five difficulties, the Ura TJA header, and — against a recorded

SC2_INTEGRATION.md

@@ -130,6 +130,87 @@ In the browser: upload audio, pick **BarScript (preview)**, pick a difficulty
 
 ---
 
+## The bar timeline
+
+Two different things are called "the grid" and they have to be kept apart.
+
+| | what it is | who decides it |
+|---|---|---|
+| **bar-local lattice** | how finely a note may sit inside one bar — the shipped `/16` | the release package (`SHIP_GRID_DENOM`), reported as `Chart lattice` |
+| **bar timeline** | where each barline falls in the audio | the caller, reported as `Bar grid` / `Tempo map` |
+
+Only the second can express a tempo change, and until now the Space could not.
+`sc2_loader.SoftChart2.generate` synthesized the timeline from one scalar BPM,
+`bar_sec = (240/bpm) * num/den` tiled from the first downbeat, which is uniform
+by construction. It now takes **either** `bpm=` (that same uniform tiling) **or**
+`grid=` (a supplied timeline used verbatim) — exactly one, never both.
+
+`softchart/barscript_grid.py` builds the supplied timeline from the beat fit the
+Space already computes. `grid.fit_grid_piecewise` returns downbeats that are
+*not* evenly spaced when it splices in a local tempo, so the fix is to pass those
+times through as the bar edges instead of re-tiling from `fit["bpm"]`. Both the
+decoder and the frozen TJA writer read every time out of `measure_edges` —
+`write_tja_slots` recomputes `60 * quarter_beats[m] / (edges[m+1] - edges[m])`
+per bar and emits `#BPMCHANGE` whenever it moves — so nothing else had to change,
+and neither `softchart/sc2/` nor the shipping tree was touched.
+
+The route is chosen by the fit's own gate, not by a new threshold:
+
+| | timeline | `grid_source` |
+|---|---|---|
+| fit passes `fit["ok"]` | the fitted downbeats, verbatim | `piecewise` |
+| fit fails the gate, or none | uniform tiling from one BPM | `uniform_fallback` |
+
+A manual BPM needs no special case: `fit_grid_fixed_bpm` trusts the user's period
+and estimates only the phase, so its downbeats are evenly spaced and the same
+route yields a uniform timeline at the requested tempo.
+
+On top of `fit["ok"]` the builder applies structural checks only — a bar must
+imply 30–400 BPM (a strict superset of what the estimator can emit), the fit
+must cover the audio within four extrapolated bars, and a splice joint shorter
+than one 400 BPM bar is merged within a 5 % budget. Every repair is counted and
+reported.
+
+### How well it works, measured
+
+60 held-out songs from the `test` split, full length, through the deployed beat
+path (v1.7 beat head + `fit_grid_piecewise`); ground truth for "does this song
+change tempo" is the authored trace.
+
+| trace says | served non-uniform | served uniform (piecewise route) | fell back to one BPM |
+|---|---|---|---|
+| changes tempo (n=30) | 8 (27 %) | 14 (47 %) | 8 (27 %) |
+| constant (n=30) | **8 (27 %)** | 16 (53 %) | 6 (20 %) |
+
+So 16 songs were served a non-uniform timeline and **8 of them do not change
+tempo** — at this sample size the verdict is a coin flip. Nine of the 16 span a
+factor of ≥ 1.9 between longest and shortest bar, six of those landing within
+1 % of exactly ×2: the signature of a barline the estimator split in two, not of
+a tempo change. Six of the nine wide-spread grids are on trace-constant songs.
+
+Two consequences, both deliberate:
+
+1. The interface says `follows the estimated barlines`, gives the spread as a
+   number, and states that a split barline and a real tempo change are not told
+   apart. It does **not** say the tempo change was captured.
+2. No new gate was added to suppress the wide-spread cases. The bound that would
+   catch them has to be *relative* to the local bar period — the absolute
+   30–400 BPM bound cannot, since a 360 BPM bar beside 180 BPM bars is inside
+   it — and specifying and validating such a rule is a design change, not a
+   deployment one. Inventing a threshold here and shipping it unvalidated would
+   be worse than shipping the measurement.
+
+Variable **meter** is not supported at all. `fit_grid` reports a single meter, so
+`measure_num`/`measure_den` are constant and `meter_source` is recorded as
+`fit_estimate`. The grid dict and the TJA writer can both express a per-bar
+`#MEASURE`, but nothing in this stack estimates one from audio; writing one would
+be fabrication. Recomputing the corpus from `trace` over 1 134 songs / 4 449
+charts, 29.0 % of charts change tempo and 52.4 % change meter — the earlier
+combined figure of 62.3 % overstated what this module reaches by about a factor
+of two, and the Space copy of the module says so in its docstring.
+
+---
+
 ## Tests
 
 Three suites, all CPU, no network required (the third reads published models
@@ -142,8 +223,17 @@ python scripts/test_app_wiring.py     # routing, resolution order, ura, limitati
 HF_HUB_OFFLINE=1 python scripts/test_space_e2e.py   # real weights, real music
 ```
 
-Current status: **all green** — 7 vendor checks, 117 wiring checks, 380
-end-to-end checks.
+Current status: **all green** — 6 vendor checks, 147 wiring checks, 380
+end-to-end checks (6 songs × 5 difficulties, plus the published-model replay).
+
+30 of the wiring checks are new with the bar timeline: that the loader is handed
+a supplied grid and not a scalar BPM, that the served bar edges are bitwise the
+fitted downbeats, that a two-tempo fit comes out with two bar lengths at the
+right tempi, that a constant song and a manual BPM both come out uniform, that a
+failed quality gate falls back and says so with its numbers, that the loader
+refuses an ambiguous `bpm=`+`grid=` call and a grid whose lattice disagrees with
+`grid_denom`, and — through the real decoder and the frozen TJA writer — that a
+two-tempo timeline reaches the file as a header `BPM:120` plus `#BPMCHANGE 150`.
 
 15 of the wiring checks cover package resolution: that `$SC2_PACKAGE_DIR`
 outranks a local copy and the Hub, that an unsatisfiable `$SC2_PACKAGE_DIR`
@@ -195,6 +285,12 @@ Every chart, on every difficulty, satisfies:
 - the note and span counts shown in the UI equal the counts recovered by
   re-parsing the file.
 
+On these six songs the bar timeline is uniform either way: four fits pass their
+gate and produce evenly spaced barlines, two miss it and fall back, so the served
+grids are identical to what shipped before. The excerpts are 60 s taken from 20 %
+into each song, which is why the fits are worse here than on full songs. The
+non-uniform path is measured separately, on full-length audio, above.
+
 ### Ura is harder than Oni — but by much less than authored charts
 
 Note counts per course, same song. Generated rows cover the **60 s excerpt**;
@@ -288,8 +384,10 @@ interface when BarScript is selected.
 | §2.4 | At the top of the **density knob**, drumrolls are squeezed out: span yield falls to 33 % of authored. The highest setting is not recommended. |
 | corpus | **Ura was trained on 208 charts** against roughly 1 100 per other course; expect lower quality. |
 
-Two operational notes are shown with them: the plan switches do not apply, and
-BarScript needs a beat grid.
+Four operational notes are shown with them: the plan switches do not apply,
+BarScript needs a beat grid, a tempo change is followed only when the beat fit
+passes its gate (and the result says which happened), and a time-signature
+change is never followed.
 
 ### The Ura warning applies to every model
 
@@ -339,10 +437,14 @@ substitution entirely.
    drumrolls. The ladder above shows ura landing *below* authored density, which
    is consistent with the knob not delivering what it asks for.
 
-4. **Piecewise-tempo songs are flattened.** BarScript decodes one uniform tempo; when
-   the grid fit finds several segments the result discloses this under
-   `tempo_map`. The six test songs are single-tempo, so the effect is
-   unquantified.
+4. **A non-uniform bar timeline is served, but its accuracy is a coin flip.**
+   BarScript now decodes onto the fitted barlines, so a tempo change *can*
+   survive — see [The bar timeline](#the-bar-timeline). Over 60 held-out songs
+   only 8 of the 16 non-uniform timelines belong to a song that actually changes
+   tempo, and 9 of the 16 carry a ≥ 1.9× bar-length spread that looks like a
+   split barline. The relative bound that would catch those is a design change
+   and is not made here; the interface reports the spread and the ambiguity
+   instead of claiming a tempo change was captured.
 
 5. **No human play-testing.** Every claim here is structural or statistical.
    Whether these charts are *good* — groove, pattern quality, whether the ura
@@ -358,7 +460,8 @@ substitution entirely.
 | path | role |
 |---|---|
 | `spaces/softchart/sc2/` | vendored BarScript serving code, 8 modules, byte-identical to the frozen shipping tree (md5 checked against the package at every load) |
-| `spaces/softchart/sc2_loader.py` | the only bridge: package loading, integrity checks, serving contract, `COURSE:` header rewrite, limitation text |
+| `spaces/softchart/sc2_loader.py` | the only bridge: package loading, integrity checks, serving contract, supplied-grid route, `COURSE:` header rewrite, limitation text |
+| `spaces/softchart/barscript_grid.py` | builds the supplied bar timeline from a beat fit, so a tempo change reaches the decoder and the TJA |
 | `spaces/app.py` | routing, ura, the BarScript branch, `/api/capabilities` |
 | `spaces/static/` | model menu, ura option, limitation panel |
 | `spaces/scripts/test_sc2_vendor.py` | vendored tree matches the package; 1.x untouched |

app.py

@@ -21,6 +21,8 @@ from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
 from softchart import sc2_loader
+from softchart.barscript_grid import (GridFitError, barscript_grid_from_fit,
+                                      describe_grid)
 from softchart.generate import generate_song, generate_song_slot, load_hf
 from softchart.fonts import cjk_font_path
 from softchart.grid import debias_to_grid, fit_grid_fixed_bpm, fit_grid_piecewise
@@ -414,22 +416,32 @@ def render_audio_plan(mel, title, course, out_path, plan=None):
     return out_path
 
 
-def generate_sc2(sc2, mel, grid, dbs, bpm, course, level, wave_name, title,
-                 *, sampling, temperature, top_p, seed=0):
-    """Run the BarScript release. Returns ``(generated, tja, extra_metrics)``.
-
-    BarScript decodes onto a bar lattice supplied by the caller, so it needs both a
-    tempo and the audio time of the first downbeat. Neither can be guessed: a
-    lattice anchored on the wrong phase puts every barline in the wrong place,
-    and the chart would look like a model defect rather than a missing input.
-    The route therefore fails closed when no downbeat is available.
-
-    Sampling parameters are left at the package's recorded serving contract
-    unless the user turns creative sampling on. Anything overridden is reported
-    back, because the model card's measurements describe the recorded values.
+def sc2_bar_grid(sc2, fit, beat_fit_raw, dbs, bpm, duration_sec):
+    """Bar timeline for a BarScript decode: ``(grid, anchor, offset_sec)``.
+
+    BarScript decodes onto a bar timeline supplied by the caller, so it needs
+    the audio time of the first downbeat. That cannot be guessed: a timeline
+    anchored on the wrong phase puts every barline in the wrong place, and the
+    chart would look like a model defect rather than a missing input. The route
+    therefore fails closed when no downbeat is available.
+
+    ``fit`` is the beat fit that PASSED its own quality gate, or None. When one
+    is present its downbeats become the bar edges verbatim, so a tempo change
+    the fit found survives into the decode and into the TJA's ``#BPMCHANGE``
+    lines. ``fit_grid_piecewise`` returns evenly spaced downbeats for a
+    constant-tempo song and for the manual-BPM refit (``fit_grid_fixed_bpm``
+    trusts the user's period and estimates only the phase), so those two cases
+    take the same route and simply come out uniform -- there is no separate
+    uniform branch to keep in sync.
+
+    Without a passing fit the grid is re-tiled from one scalar BPM, which is
+    the behaviour this route has always had and cannot represent a tempo
+    change. ``beat_fit_raw`` -- the fit that failed the gate, if there was one
+    -- is handed to the builder so the fallback records WHY it happened
+    (inlier fraction and RMS) instead of reporting a missing fit.
     """
-    if grid is not None and len(grid.get("downbeats", [])):
-        offset_sec = float(grid["downbeats"][0])
+    if fit is not None and len(fit.get("downbeats", [])):
+        offset_sec = float(fit["downbeats"][0])
         anchor = "fitted beat grid"
     elif dbs is not None and len(dbs):
         offset_sec = float(dbs[0])
@@ -440,35 +452,131 @@ def generate_sc2(sc2, mel, grid, dbs, bpm, course, level, wave_name, title,
             "them without one. Leave the beat grid switched on, or enter the "
             "song's BPM in Advanced settings, and try again."
         )
+    try:
+        grid = barscript_grid_from_fit(
+            fit if fit is not None else beat_fit_raw, duration_sec,
+            denom=sc2_loader.SHIP_GRID_DENOM, spec=sc2.spec,
+            on_invalid="fallback", fallback_bpm=float(bpm),
+            fallback_offset=offset_sec,
+        )
+    except GridFitError as exc:  # only reachable if the fallback itself fails
+        raise RuntimeError(
+            f"Could not build a bar timeline for this song: {exc}"
+        ) from exc
+    return grid, anchor, offset_sec
+
+
+def sc2_grid_metrics(grid, grid_info, anchor, offset_sec):
+    """How the bar timeline is reported to the user.
+
+    The user's question is "was this song's tempo change handled?", so the
+    answer names the route (estimated barlines vs. one uniform tempo), says
+    whether the timeline that came out actually varies, and gives the fit's
+    quality numbers. A fallback is never silent: it carries the builder's own
+    reason string.
+    """
+    meta = grid_info.get("grid_meta") or {}
+    quality = grid_info.get("fit_quality")
+    source = grid_info.get("grid_source", "unknown")
+    n_tempi = int(grid_info.get("n_distinct_bar_sec", 1))
+    inlier = rms = "n/a"
+    if quality is not None:
+        if quality["inlier_frac"] is not None:
+            inlier = f"{quality['inlier_frac']:.3f}"
+        if quality["rms_ms"] is not None:
+            rms = f"{quality['rms_ms']:.1f} ms"
+    out = {
+        "grid_anchor": f"{anchor}, first downbeat {offset_sec:.3f} s",
+        "bar_grid": describe_grid(grid),
+    }
+    if source == "piecewise" and n_tempi > 1:
+        # Deliberately NOT "the tempo change was captured". The grid follows
+        # the estimated barlines, and a barline the estimator split in two is
+        # indistinguishable, from here, from a bar at twice the tempo -- both
+        # land as a x2 spread. Measured over 60 held-out songs, 16 were served
+        # a non-uniform grid and only 8 of those actually change tempo per the
+        # authored trace, 9 of the 16 spanning a factor >= 1.9. So the spread
+        # is stated as the measurement it is, with the ambiguity attached.
+        spread = grid_info["bar_bpm_max"] / max(grid_info["bar_bpm_min"], 1e-9)
+        out["tempo_map"] = (
+            f"follows the estimated barlines — {n_tempi} distinct bar lengths, "
+            f"{grid_info['bar_bpm_min']:.1f}–{grid_info['bar_bpm_max']:.1f} BPM "
+            f"across {grid_info['n_bars']} bars, spread ×{spread:.2f}. "
+            f"A barline split in two and a genuine tempo change are not "
+            f"told apart here; a spread near ×2 is the signature of both."
+        )
+    elif source == "piecewise":
+        out["tempo_map"] = (
+            f"constant — the estimated barlines are evenly spaced at "
+            f"{grid_info['bar_bpm_min']:.1f} BPM, so no tempo change was found"
+        )
+    else:
+        # The overwhelmingly common fallback is a fit that missed its own
+        # quality gate, and the builder's reason string then repeats the two
+        # numbers at full float precision. Those numbers are stated here
+        # rounded, from ``fit_quality`` rather than by re-reading the string;
+        # every OTHER reason (coverage, joint-repair budget, a malformed
+        # downbeat sequence) is quoted verbatim, since nothing else carries it.
+        why = (f"the beat fit did not pass its quality gate: inlier {inlier}, "
+               f"RMS {rms}") if (quality is not None and not quality["ok"]) \
+            else (meta.get("reason") or "no reason recorded")
+        out["tempo_map"] = (
+            f"flattened to one uniform {grid_info['bpm']:.1f} BPM — a tempo "
+            f"change in this song would NOT be represented ({why})"
+        )
+    if quality is not None:
+        out["beat_fit"] = (
+            f"{'passed' if quality['ok'] else 'FAILED its quality gate'} — "
+            f"inlier {inlier}, RMS {rms}, {quality['n_segments']} tempo "
+            f"segment(s) found"
+        )
+    else:
+        out["beat_fit"] = "no beat fit — bars tiled from a single BPM"
+    repairs = []
+    if meta.get("joint_bars_merged"):
+        repairs.append(f"{meta['joint_bars_merged']} splice-joint bar(s) merged")
+    if meta.get("tail_bars_extrapolated"):
+        repairs.append(f"{meta['tail_bars_extrapolated']} tail bar(s) extrapolated")
+    if repairs:
+        out["grid_repairs"] = "; ".join(repairs)
+    return out
+
+
+def generate_sc2(sc2, mel, fit, beat_fit_raw, dbs, bpm, course, level,
+                 wave_name, title, *, sampling, temperature, top_p, seed=0):
+    """Run the BarScript release. Returns ``(generated, tja, extra_metrics)``.
+
+    Sampling parameters are left at the package's recorded serving contract
+    unless the user turns creative sampling on. Anything overridden is reported
+    back, because the model card's measurements describe the recorded values.
+    """
+    duration_sec = mel.shape[1] / FPS
+    grid, anchor, offset_sec = sc2_bar_grid(
+        sc2, fit, beat_fit_raw, dbs, bpm, duration_sec)
 
     overrides = {}
     if sampling:
         overrides = {"greedy": False, "temperature": float(temperature),
                      "top_p": float(top_p)}
     result = sc2.generate(
-        mel, course, level=level, bpm=float(bpm), offset_sec=offset_sec,
+        mel, course, level=level, grid=grid,
         density_bucket=COURSE_DENS[course], seed=seed,
         grid_denom=sc2_loader.SHIP_GRID_DENOM,
         title=title, wave=wave_name, **overrides,
     )
     grid_info = result["grid"]
-    segments = int(grid.get("n_segments", 1)) if grid is not None else 1
     extra = {
-        "chart_grid": (f"/{grid_info['denom']} uniform"
+        # the bar-LOCAL lattice: how finely a note may sit inside one bar.
+        # Unrelated to the bar timeline reported by tempo_map below.
+        "chart_grid": (f"/{grid_info['denom']} per bar"
                        + ("" if grid_info["triplets_representable"]
                           else " — triplets impossible")),
-        "grid_anchor": f"{anchor}, first downbeat {offset_sec:.3f} s",
         "density_bucket": result["density_bucket"],
         "sampling": ("user override: " + ", ".join(
             f"{k}={v}" for k, v in sorted(result["serving_overrides"].items()))
             ) if result["serving_overrides"] else "package defaults",
+        **sc2_grid_metrics(grid, grid_info, anchor, offset_sec),
     }
-    if segments > 1:
-        extra["tempo_map"] = (
-            f"flattened — the fit found {segments} tempo segments, BarScript "
-            f"decodes "
-            f"one uniform tempo ({bpm:.1f} BPM)"
-        )
     if not result["motif"]["verified"]:
         raise RuntimeError(
             "BarScript decoded without the motif constraint the release "
@@ -557,6 +665,14 @@ def capabilities():
                 "#GOGO sections are written.",
                 "BarScript needs a beat grid. Leave the beat grid on, or enter the "
                 "song's BPM, so its bar lattice has a downbeat to sit on.",
+                "Tempo changes are followed when the beat fit passes its quality "
+                "gate: the estimated barlines become the bars, so the chart and "
+                "its #BPMCHANGE lines track the song. If the fit fails the gate "
+                "the bars are tiled from one BPM instead and a tempo change is "
+                "not represented — the result says which happened.",
+                "Time-signature changes are never followed. Nothing in this "
+                "system estimates meter per bar from audio, so one estimated "
+                "time signature is used for the whole song.",
             ]
         models.append(entry)
     return {
@@ -655,9 +771,14 @@ def generate_chart(
             "beat", 0.21, "Finding the beat",
             "Finding beats and tempo.",
         )
-        grid = dbs = None
+        # ``grid`` is the fit that PASSED its own quality gate (None otherwise).
+        # ``beat_fit_raw`` keeps the last fit that was actually computed, gate
+        # or no gate, so a failed gate can be reported with its numbers instead
+        # of disappearing into a silent fallback.
+        grid = dbs = beat_fit_raw = None
         if use_beat:
             grid = fit_grid_piecewise(models["beat"], mel, device=DEVICE)
+            beat_fit_raw = grid
             if grid is not None:
                 dbs = grid["downbeats"] if grid["ok"] else grid["db_peaks"]
                 if not grid["ok"]:
@@ -666,6 +787,8 @@ def generate_chart(
             bpm = bpm_override
             if use_beat and (grid is None or abs(grid["bpm"] - bpm) > 0.5):
                 fixed_grid = fit_grid_fixed_bpm(models["beat"], mel, bpm, device=DEVICE)
+                if fixed_grid is not None:
+                    beat_fit_raw = fixed_grid
                 grid = fixed_grid if fixed_grid is not None and fixed_grid["ok"] else None
                 if grid is not None:
                     dbs = grid["downbeats"]
@@ -718,7 +841,8 @@ def generate_chart(
         slot_used = grid is not None
         if sc2_used:
             generated, tja, extra_metrics = generate_sc2(
-                sc2, mel, grid, dbs, bpm, course, level, wave_name, title,
+                sc2, mel, grid, beat_fit_raw, dbs, bpm, course, level,
+                wave_name, title,
                 sampling=sampling, temperature=temperature, top_p=top_p,
             )
             slot_used = True

scripts/test_app_wiring.py

@@ -100,6 +100,38 @@ def fake_grid(bpm=150.0, n_bars=8, phase=0.25):
             "rms_ms": 7.5, "db_peaks": downbeats, "ok": True}
 
 
+def fake_vartempo_grid(bpm_a=120.0, bpm_b=150.0, bars_a=6, bars_b=5,
+                       phase=0.25):
+    """A fit whose downbeats are NOT evenly spaced: two tempo sections.
+
+    This is the shape ``fit_grid_piecewise`` returns after a splice -- the
+    local tempo lives in the SPACING of the downbeats, not in any scalar
+    field. A grid builder that re-tiles from ``bpm`` cannot reproduce it,
+    which is exactly what the piecewise route has to be tested against.
+
+    The defaults tile the harness's 20 s mel, as a real fit does, so nothing
+    here is measuring the grid builder's tail-extrapolation budget by accident.
+    """
+    bar_a, bar_b = 4 * 60.0 / bpm_a, 4 * 60.0 / bpm_b
+    db_a = phase + np.arange(bars_a) * bar_a
+    db_b = db_a[-1] + bar_a + np.arange(bars_b) * bar_b
+    downbeats = np.concatenate([db_a, db_b])
+    return {"bpm": bpm_a, "beat": 60.0 / bpm_a, "bar": bar_a, "meter": 4,
+            "phase": phase, "downbeats": downbeats,
+            "beats": downbeats, "n_db_peaks": len(downbeats),
+            "n_beat_peaks": 4 * len(downbeats), "inlier_frac": 0.93,
+            "rms_ms": 6.2, "db_peaks": downbeats, "ok": True,
+            "piecewise": True, "n_segments": 2,
+            "segments": [(float(phase), bpm_a), (float(db_b[0]), bpm_b)]}
+
+
+def fake_failed_grid(bpm=150.0, n_bars=8, phase=0.25):
+    """A fit that did not pass ``grid.fit_grid``'s own quality gate."""
+    grid = fake_grid(bpm, n_bars, phase)
+    grid.update({"ok": False, "inlier_frac": 0.41, "rms_ms": 62.7})
+    return grid
+
+
 def fake_generation():
     return {"hits": [{"t": 1.0, "type": "don"}, {"t": 1.5, "type": "ka"}],
             "spans": [{"t0": 2.0, "t1": 3.0, "type": "roll"}],
@@ -115,7 +147,8 @@ TJA_STUB = "\n".join([
 
 def harness(module, calls, *, course="oni", model_choice=None, sampling=False,
             use_planner=True, auto_plan_on=True, use_beat=True, level=9,
-            bpm_override=0.0, audio_path=None, workdir=None):
+            bpm_override=0.0, audio_path=None, workdir=None,
+            beat_fit=None, fixed_fit=None):
     """Drive ``module.generate_chart`` with every heavy dependency recorded.
 
     Patches the module in place; the caller restores it. Returns the payload
@@ -148,8 +181,12 @@ def harness(module, calls, *, course="oni", model_choice=None, sampling=False,
     wav = np.zeros(int(20 * 22050), dtype=np.float32)
 
     patch("load_logmel", record("load_logmel", lambda: (mel, wav)))
-    patch("fit_grid_piecewise", record("fit_grid_piecewise", fake_grid))
-    patch("fit_grid_fixed_bpm", record("fit_grid_fixed_bpm", fake_grid))
+    # ``beat_fit`` / ``fixed_fit`` default to the constant-tempo fit the golden
+    # trace was recorded against, so passing neither replays legacy behaviour.
+    patch("fit_grid_piecewise",
+          record("fit_grid_piecewise", beat_fit or fake_grid))
+    patch("fit_grid_fixed_bpm",
+          record("fit_grid_fixed_bpm", fixed_fit or fake_grid))
     patch("learned_plan", record("learned_plan", [[0.0, 4.0, 5, 0]]))
     patch("auto_plan", record("auto_plan", [[0.0, 4.0, 3, 0]]))
     patch("generate_song_slot", record("generate_song_slot", fake_generation))
@@ -533,24 +570,46 @@ def test_planner_fallback():
 # 4. the BarScript route
 
 
-def test_sc2_conditions():
-    """What the app hands the BarScript loader, with the loader itself recorded."""
-    seen = {}
+class FakeSpec:
+    """Enough of a ``BarscriptSpec`` for the grid builder's provenance record."""
+
+    labels_version = "test-labels"
+
+
+def make_fake_sc2(seen):
+    """A recording stand-in for the loaded release.
+
+    ``generate`` records what it was handed and then builds its ``grid``
+    report with the LOADER's own ``_supplied_grid_info``, so the metric text
+    the app derives is checked against the real provenance shape rather than
+    a stub's idea of it.
+    """
 
     class FakeSC2:
         package_dir = "/tmp/nonexistent-package"
+        spec = FakeSpec()
 
         def generate(self, mel, course, level=None, **kwargs):
             seen["mel"] = mel.shape
             seen["course"] = course
             seen["level"] = level
             seen.update(kwargs)
+            grid = kwargs.get("grid")
+            if grid is not None:
+                sc2_loader._check_supplied_grid(grid, kwargs.get("grid_denom"))
+                grid_info = sc2_loader._supplied_grid_info(
+                    grid, mel.shape[1] / FPS)
+            else:
+                denom = kwargs.get("grid_denom", 16)
+                grid_info = {"source": "bpm", "denom": denom,
+                             "bpm": kwargs["bpm"],
+                             "offset_sec": kwargs["offset_sec"],
+                             "n_bars": 1,
+                             "triplets_representable": denom % 3 == 0}
+            grid_info["profile"] = "default"
             return {
                 "tja": TJA_STUB, "gen": fake_generation(),
-                "grid": {"source": "bpm", "denom": kwargs.get("grid_denom", 16),
-                         "bpm": kwargs["bpm"], "offset_sec": kwargs["offset_sec"],
-                         "triplets_representable": kwargs.get("grid_denom", 16) % 3 == 0,
-                         "profile": "default"},
+                "grid": grid_info,
                 "serving": {}, "serving_overrides": {
                     k: kwargs[k] for k in ("greedy", "temperature", "top_p")
                     if k in kwargs},
@@ -559,66 +618,22 @@ def test_sc2_conditions():
                 "n_notes": 2, "n_spans": 1, "experimental": True,
             }
 
+    return FakeSC2()
+
+
+def run_sc2(course="oni", sampling=False, **kw):
+    """One BarScript request against the recording loader.
+
+    Returns ``(seen, payload, calls)``: the kwargs the loader was handed, the
+    final streamed payload, and the ordered call list.
+    """
+    seen, calls = {}, []
     saved_get_sc2, saved_beat = APP.get_sc2, APP.sc2_beat_model
     saved_available = APP.available_models
-    APP.get_sc2 = lambda: FakeSC2()
+    APP.get_sc2 = lambda: make_fake_sc2(seen)
     APP.sc2_beat_model = lambda: Recorder("beat", [])
     APP.available_models = lambda: list(APP.MODELS) + [APP.SC2_MODEL]
-    ok = True
     try:
-        for course, sampling in (("oni", False), ("ura", True)):
-            seen.clear()
-            calls = []
-            with tempfile.TemporaryDirectory() as audio_dir:
-                audio_path = os.path.join(audio_dir, "song.ogg")
-                with open(audio_path, "wb") as f:
-                    f.write(b"OggS")
-                workdir = tempfile.mkdtemp(prefix="softchart-work-")
-                saved_mkdtemp = tempfile.mkdtemp
-                tempfile.mkdtemp = lambda *a, **k: workdir
-                try:
-                    payload = harness(APP, calls, course=course,
-                                      model_choice=APP.SC2_MODEL,
-                                      sampling=sampling, audio_path=audio_path,
-                                      workdir=workdir)
-                finally:
-                    tempfile.mkdtemp = saved_mkdtemp
-
-            grid = fake_grid()
-            ok &= check(f"BarScript ({course}): bpm and first-downbeat offset from the fitted grid",
-                        seen.get("bpm") == grid["bpm"]
-                        and abs(seen.get("offset_sec", -1) - float(grid["downbeats"][0])) < 1e-9,
-                        f"bpm={seen.get('bpm')} offset={seen.get('offset_sec')}")
-            ok &= check(f"BarScript ({course}): course and density bucket",
-                        seen.get("course") == course
-                        and seen.get("density_bucket") == APP.COURSE_DENS[course],
-                        f"{seen.get('course')} bucket={seen.get('density_bucket')}")
-            ok &= check(f"BarScript ({course}): ships on the /16 deployment lattice",
-                        seen.get("grid_denom") == sc2_loader.SHIP_GRID_DENOM)
-            if sampling:
-                ok &= check(f"BarScript ({course}): creative sampling is passed as an override",
-                            seen.get("greedy") is False and seen.get("temperature") == 0.8
-                            and seen.get("top_p") == 0.9, f"{seen.get('greedy')}")
-            else:
-                ok &= check(f"BarScript ({course}): package serving contract left alone",
-                            not {"greedy", "temperature", "top_p"} & set(seen),
-                            f"{sorted(set(seen) & {'greedy', 'temperature', 'top_p'})}")
-
-            metrics = payload[-1].get("metrics", {})
-            ok &= check(f"BarScript ({course}): the /16 lattice and its triplet gap are shown",
-                        "triplets impossible" in metrics.get("chart_grid", ""),
-                        metrics.get("chart_grid", ""))
-            ok &= check(f"BarScript ({course}): the plan switches are reported as unused",
-                        metrics.get("plan_source") == "Not used — BarScript takes no plan",
-                        metrics.get("plan_source", ""))
-            names = [c[0] for c in calls]
-            ok &= check(f"BarScript ({course}): the 1.x generators are never called",
-                        not {"generate_song", "generate_song_slot",
-                             "write_tja_slots", "snap_chart"} & set(names),
-                        f"{names}")
-
-        # no downbeat -> refuse, rather than anchor the bars on an arbitrary phase
-        calls = []
         with tempfile.TemporaryDirectory() as audio_dir:
             audio_path = os.path.join(audio_dir, "song.ogg")
             with open(audio_path, "wb") as f:
@@ -627,23 +642,213 @@ def test_sc2_conditions():
             saved_mkdtemp = tempfile.mkdtemp
             tempfile.mkdtemp = lambda *a, **k: workdir
             try:
-                payload = harness(APP, calls, course="oni", use_beat=False,
-                                  model_choice=APP.SC2_MODEL, bpm_override=150.0,
-                                  audio_path=audio_path, workdir=workdir)
+                payload = harness(APP, calls, course=course,
+                                  model_choice=APP.SC2_MODEL,
+                                  sampling=sampling, audio_path=audio_path,
+                                  workdir=workdir, **kw)
             finally:
                 tempfile.mkdtemp = saved_mkdtemp
-        last = payload[-1]
-        ok &= check("BarScript: fails closed without a downbeat anchor",
-                    last.get("kind") == "error" and "downbeat" in last.get("detail", ""),
-                    last.get("detail", ""))
     finally:
         APP.get_sc2, APP.sc2_beat_model = saved_get_sc2, saved_beat
         APP.available_models = saved_available
+    return seen, payload[-1], calls
+
+
+def test_sc2_conditions():
+    """What the app hands the BarScript loader, with the loader itself recorded."""
+    ok = True
+    for course, sampling in (("oni", False), ("ura", True)):
+        seen, last, calls = run_sc2(course=course, sampling=sampling)
+
+        fit = fake_grid()
+        grid = seen.get("grid")
+        ok &= check(f"BarScript ({course}): the bar timeline is SUPPLIED, not synthesized",
+                    isinstance(grid, dict) and seen.get("bpm") is None,
+                    f"grid={type(grid).__name__} bpm={seen.get('bpm')}")
+        ok &= check(f"BarScript ({course}): bar edges come from the fitted downbeats",
+                    grid is not None
+                    and np.array_equal(np.asarray(grid["measure_edges"])[:len(fit["downbeats"])],
+                                       np.asarray(fit["downbeats"]))
+                    and grid["bpm"] == fit["bpm"],
+                    f"bpm={None if grid is None else grid['bpm']}")
+        ok &= check(f"BarScript ({course}): course and density bucket",
+                    seen.get("course") == course
+                    and seen.get("density_bucket") == APP.COURSE_DENS[course],
+                    f"{seen.get('course')} bucket={seen.get('density_bucket')}")
+        ok &= check(f"BarScript ({course}): ships on the /16 deployment lattice",
+                    seen.get("grid_denom") == sc2_loader.SHIP_GRID_DENOM
+                    and set(grid["bar_denoms"]) == {sc2_loader.SHIP_GRID_DENOM},
+                    f"{sorted(set(grid['bar_denoms']))}")
+        if sampling:
+            ok &= check(f"BarScript ({course}): creative sampling is passed as an override",
+                        seen.get("greedy") is False and seen.get("temperature") == 0.8
+                        and seen.get("top_p") == 0.9, f"{seen.get('greedy')}")
+        else:
+            ok &= check(f"BarScript ({course}): package serving contract left alone",
+                        not {"greedy", "temperature", "top_p"} & set(seen),
+                        f"{sorted(set(seen) & {'greedy', 'temperature', 'top_p'})}")
+
+        metrics = last.get("metrics", {})
+        ok &= check(f"BarScript ({course}): the /16 lattice and its triplet gap are shown",
+                    "triplets impossible" in metrics.get("chart_grid", ""),
+                    metrics.get("chart_grid", ""))
+        ok &= check(f"BarScript ({course}): the plan switches are reported as unused",
+                    metrics.get("plan_source") == "Not used — BarScript takes no plan",
+                    metrics.get("plan_source", ""))
+        names = [c[0] for c in calls]
+        ok &= check(f"BarScript ({course}): the 1.x generators are never called",
+                    not {"generate_song", "generate_song_slot",
+                         "write_tja_slots", "snap_chart"} & set(names),
+                    f"{names}")
+
+    # no downbeat -> refuse, rather than anchor the bars on an arbitrary phase
+    _, last, _ = run_sc2(course="oni", use_beat=False, bpm_override=150.0)
+    ok &= check("BarScript: fails closed without a downbeat anchor",
+                last.get("kind") == "error" and "downbeat" in last.get("detail", ""),
+                last.get("detail", ""))
+    return ok
+
+
+def test_sc2_tempo_map():
+    """Does a tempo change reach the decoder, and is the outcome reported?
+
+    The core requirement: every bar is a slot, and the slots have to follow
+    the song when it speeds up. That is testable in one place -- the bar
+    timeline handed to the loader -- because both the decoder and the TJA
+    writer read every time out of ``measure_edges``.
+    """
+    ok = True
+
+    # 1. variable tempo, fit passes its gate -> the non-uniform barlines survive
+    seen, last, _ = run_sc2(beat_fit=fake_vartempo_grid)
+    grid = seen.get("grid")
+    metrics = last.get("metrics", {})
+    edges = np.asarray(grid["measure_edges"]) if grid else np.zeros(2)
+    bar_sec = np.diff(edges)
+    fit = fake_vartempo_grid()
+    ok &= check("tempo map: a variable-tempo fit is served as a piecewise grid",
+                grid is not None and grid.get("grid_source") == "piecewise",
+                f"{None if grid is None else grid.get('grid_source')}")
+    inside = np.asarray(fit["downbeats"])
+    inside = inside[inside < 20.0]  # the harness mel is 20 s
+    ok &= check("tempo map: the served bar edges ARE the fitted downbeats (bitwise)",
+                grid is not None
+                and np.array_equal(edges[:len(inside)], inside)
+                and len(edges) == len(inside) + 1,
+                f"{len(edges)} edges vs {len(inside)} in-audio downbeats")
+    ok &= check("tempo map: the served grid really contains two bar lengths",
+                np.unique(np.round(bar_sec, 6)).size == 2,
+                f"{sorted(np.unique(np.round(bar_sec, 3)).tolist())}")
+    ok &= check("tempo map: 120 and 150 BPM bars both survive",
+                abs(60.0 * 4 / bar_sec.min() - 150.0) < 1e-6
+                and abs(60.0 * 4 / bar_sec.max() - 120.0) < 1e-6,
+                f"{60.0 * 4 / bar_sec.max():.2f}-{60.0 * 4 / bar_sec.min():.2f} BPM")
+    ok &= check("tempo map: the UI says the grid follows the estimated barlines",
+                metrics.get("tempo_map", "").startswith("follows the estimated barlines")
+                and "2 distinct bar lengths" in metrics.get("tempo_map", ""),
+                metrics.get("tempo_map", ""))
+    ok &= check("tempo map: the UI states the spread and does not claim it is a tempo change",
+                "spread ×1.25" in metrics.get("tempo_map", "")
+                and "not told apart here" in metrics.get("tempo_map", ""),
+                metrics.get("tempo_map", ""))
+    ok &= check("tempo map: the UI reports the fit quality that let it through",
+                metrics.get("beat_fit", "").startswith("passed")
+                and "0.930" in metrics.get("beat_fit", "")
+                and "6.2 ms" in metrics.get("beat_fit", ""),
+                metrics.get("beat_fit", ""))
+    ok &= check("tempo map: the bar-grid line names the source and the BPM range",
+                "estimated barlines" in metrics.get("bar_grid", "")
+                and "120.0-150.0 BPM" in metrics.get("bar_grid", ""),
+                metrics.get("bar_grid", ""))
+
+    # 2. constant tempo -> same route, and the UI does not claim a tempo change
+    seen, last, _ = run_sc2()
+    metrics = last.get("metrics", {})
+    ok &= check("tempo map: a constant-tempo song takes the same route",
+                seen["grid"].get("grid_source") == "piecewise",
+                seen["grid"].get("grid_source"))
+    ok &= check("tempo map: and is reported as constant, not as a tempo change",
+                metrics.get("tempo_map", "").startswith("constant")
+                and "150.0 BPM" in metrics.get("tempo_map", ""),
+                metrics.get("tempo_map", ""))
+
+    # 3. the fit fails its own gate -> uniform fallback, stated with its numbers
+    seen, last, _ = run_sc2(beat_fit=fake_failed_grid)
+    grid, metrics = seen.get("grid"), last.get("metrics", {})
+    ok &= check("tempo map: a fit that fails its gate falls back to a uniform grid",
+                grid is not None and grid.get("grid_source") == "uniform_fallback",
+                f"{None if grid is None else grid.get('grid_source')}")
+    ok &= check("tempo map: the fallback is NOT silent -- it says tempo change is lost",
+                "NOT be represented" in metrics.get("tempo_map", ""),
+                metrics.get("tempo_map", ""))
+    ok &= check("tempo map: the fallback carries the gate numbers that caused it",
+                "0.41" in metrics.get("tempo_map", "")
+                and "62.7" in metrics.get("tempo_map", ""),
+                metrics.get("tempo_map", ""))
+    ok &= check("tempo map: and the beat-fit line says the gate FAILED",
+                "FAILED its quality gate" in metrics.get("beat_fit", ""),
+                metrics.get("beat_fit", ""))
+
+    # 4. manual BPM: the user's period is trusted, so the refit is uniform
+    seen, last, calls = run_sc2(beat_fit=fake_vartempo_grid, bpm_override=180.0,
+                                fixed_fit=lambda: fake_grid(bpm=180.0, n_bars=14))
+    grid, metrics = seen.get("grid"), last.get("metrics", {})
+    bar_sec = np.diff(np.asarray(grid["measure_edges"]))
+    ok &= check("manual BPM: the fixed-BPM refit is still the grid that is served",
+                "fit_grid_fixed_bpm" in [c[0] for c in calls]
+                and abs(grid["bpm"] - 180.0) < 1e-9,
+                f"bpm={grid['bpm']}")
+    ok &= check("manual BPM: the served bars are uniform at the requested tempo",
+                np.unique(np.round(bar_sec, 6)).size == 1
+                and abs(60.0 * 4 / bar_sec[0] - 180.0) < 1e-6,
+                f"{60.0 * 4 / bar_sec[0]:.3f} BPM, "
+                f"{np.unique(np.round(bar_sec, 6)).size} distinct bar length(s)")
+    ok &= check("manual BPM: reported as constant rather than as a tempo change",
+                metrics.get("tempo_map", "").startswith("constant"),
+                metrics.get("tempo_map", ""))
+    return ok
+
+
+def test_sc2_grid_contract():
+    """The loader's own guards on a supplied bar timeline."""
+    from softchart.barscript_grid import barscript_grid_from_fit
+
+    ok = True
+    grid = barscript_grid_from_fit(fake_vartempo_grid(), 20.0,
+                                   denom=sc2_loader.SHIP_GRID_DENOM)
+    ok &= check("loader: a well-formed supplied grid passes the denominator check",
+                sc2_loader._check_supplied_grid(grid, 16) is grid)
+    for label, bad, denom in (
+            ("a missing key", {k: v for k, v in grid.items()
+                               if k != "measure_edges"}, 16),
+            ("a lattice that disagrees with grid_denom", grid, 32)):
+        try:
+            sc2_loader._check_supplied_grid(bad, denom)
+            ok &= check(f"loader: refuses {label}", False, "accepted")
+        except ValueError as exc:
+            ok &= check(f"loader: refuses {label}", True, str(exc)[:70])
+
+    info = sc2_loader._supplied_grid_info(grid, 20.0)
+    ok &= check("loader: reports that the served bars carry two tempi",
+                info["n_distinct_bar_sec"] == 2 and info["source"] == "supplied",
+                f"{info['n_distinct_bar_sec']} distinct bar lengths")
+    ok &= check("loader: carries the builder's provenance through untouched",
+                info["grid_source"] == "piecewise"
+                and info["fit_quality"]["n_segments"] == 2,
+                f"{info['grid_source']}")
     return ok
 
 
 def test_sc2_real_decode():
-    """One real 2.0 decode, if the release package is on disk."""
+    """Real 2.0 decodes, if the release package is on disk.
+
+    The variable-tempo case is the one that matters: it drives the real
+    decoder and the real TJA writer with a two-tempo bar timeline and checks
+    the timeline came out the other end, rather than asserting on a shape the
+    Space made up.
+    """
+    from softchart.barscript_grid import barscript_grid_from_fit
+
     if not sc2_loader.is_available():
         print("SKIP  2.0 real decode: no release package "
               f"({sc2_loader.default_package_dir()})")
@@ -665,6 +870,46 @@ def test_sc2_real_decode():
         ok &= check(f"BarScript real decode ({course}): lattice reported as /16 without triplets",
                     result["grid"]["denom"] == 16
                     and result["grid"]["triplets_representable"] is False)
+
+    # exactly one of bpm= / grid= -- an ambiguous call must not pick one
+    for kwargs, label in (({}, "neither bpm nor grid"),
+                          ({"bpm": 150.0, "grid": {}}, "both bpm and grid")):
+        try:
+            sc.generate(mel, "oni", level=9, seed=0, **kwargs)
+            ok &= check(f"BarScript real decode: refuses {label}", False, "accepted")
+        except ValueError as exc:
+            ok &= check(f"BarScript real decode: refuses {label}", True, str(exc)[:60])
+
+    # a real two-tempo decode, end to end through the frozen TJA writer
+    duration = mel.shape[1] / FPS
+    fit = fake_vartempo_grid(bpm_a=120.0, bpm_b=150.0, bars_a=3, bars_b=3)
+    grid = barscript_grid_from_fit(fit, duration,
+                                   denom=sc2_loader.SHIP_GRID_DENOM,
+                                   spec=sc.spec)
+    result = sc.generate(mel, "oni", level=9, grid=grid,
+                         density_bucket=APP.COURSE_DENS["oni"], seed=0,
+                         grid_denom=sc2_loader.SHIP_GRID_DENOM,
+                         title="probe", wave="song.ogg")
+    info = result["grid"]
+    ok &= check("BarScript real decode: a supplied two-tempo grid is served as such",
+                info["source"] == "supplied" and info["n_distinct_bar_sec"] == 2,
+                f"{info['source']}, {info['n_distinct_bar_sec']} bar lengths")
+    # the writer opens at the header BPM and emits #BPMCHANGE only when a bar
+    # departs from it, so the two tempi land in two different places
+    tempi = [float(ln.split()[1]) for ln in result["tja"].splitlines()
+             if ln.startswith("#BPMCHANGE")]
+    header_bpm = [float(ln[4:]) for ln in result["tja"].splitlines()
+                  if ln.startswith("BPM:")]
+    ok &= check("BarScript real decode: the second tempo reaches the TJA as #BPMCHANGE",
+                any(abs(t - 150.0) < 1e-6 for t in tempi),
+                f"header BPM {header_bpm}, #BPMCHANGE "
+                f"{sorted({round(t, 3) for t in tempi})}")
+    ok &= check("BarScript real decode: the first tempo is the TJA header BPM",
+                header_bpm == [120.0], f"{header_bpm}")
+    ok &= check("BarScript real decode: TJA OFFSET is the first fitted downbeat",
+                any(ln == f"OFFSET:{-float(grid['measure_edges'][0]):.17g}"
+                    for ln in result["tja"].splitlines()),
+                f"first edge {float(grid['measure_edges'][0]):.6f} s")
     return ok
 
 
@@ -1029,7 +1274,8 @@ def record_golden(app_path):
 def main():
     tests = [test_routing, test_courses, test_course_header,
              test_legacy_regression, test_planner_fallback,
-             test_sc2_conditions, test_sc2_package_resolution,
+             test_sc2_conditions, test_sc2_tempo_map, test_sc2_grid_contract,
+             test_sc2_package_resolution,
              test_capabilities_payload, test_sc2_real_decode]
     for test in tests:
         print(f"\n--- {test.__name__}")

scripts/test_sc2_vendor.py

@@ -319,9 +319,15 @@ def test_c_legacy_library_untouched():
         "1.x library modules changed since 2.0 was vendored in; the seven "
         f"published models are no longer a fixed baseline: {drift}")
 
+    # Space-owned modules that may sit beside the 1.x library. The list is
+    # explicit so a module arriving unnoticed is a failure, not a shrug:
+    #   sc2_loader.py       the bridge to softchart.sc2
+    #   barscript_grid.py   builds a BarScript bar timeline from a beat fit,
+    #                       so a tempo change survives into the served grid
+    # Neither is imported by any 1.x code path.
     added = sorted(n for n in os.listdir(lib)
                    if n.endswith(".py") and n not in LEGACY_MD5)
-    assert added == ["sc2_loader.py"], added
+    assert added == ["barscript_grid.py", "sc2_loader.py"], added
     return {"unchanged": len(LEGACY_MD5), "added": added}
 
 

softchart/barscript_grid.py

@@ -0,0 +1,446 @@
+"""Serving-time BarScript grid built from an ESTIMATED beat fit.
+
+Space copy
+----------
+Derived from the shipping tree's ``src/softchart/barscript_grid.py``
+(md5 7e810833ed2e5c796c5bcfa6e3c376c3).  Two deliberate differences, both
+forced by where this file now lives:
+
+1. The two lazy imports point at the vendored 2.0 subpackage
+   (``.sc2.generate``, ``.sc2.vocab``) instead of the sibling modules.  In the
+   Space, ``softchart.generate`` and ``softchart.vocab`` are the SoftChart 1.x
+   library with an incompatible token table, so the shipping tree's plain
+   ``.generate`` / ``.vocab`` would silently bind to the wrong decoder.
+2. The corpus figure quoted below is corrected.  The shipping tree's docstring
+   said "62.3 % of corpus charts contain a variable-tempo or variable-meter
+   bar"; recomputing from ``trace`` over 1 134 songs / 4 449 charts separates
+   the two, and only the TEMPO half is what this module addresses:
+   **29.0 % of charts change tempo**, 52.4 % change meter.  Variable meter is
+   explicitly out of scope (see below), so 62.3 % overstated this module's
+   reach by roughly a factor of two.
+
+Nothing else is changed; the grid arithmetic and the gates are identical.
+
+Why this module exists
+----------------------
+The BarScript decoder consumes a *supplied grid* dict --
+``{bpm, downbeats, measure_edges, measure_num, measure_den, bar_denoms}`` --
+and every note time it produces, plus every ``#BPMCHANGE`` the TJA writer
+emits, is derived from ``measure_edges`` alone.  The representation is
+therefore exact under tempo change: ``tja.write_tja_slots`` recomputes
+``bpm_m = 60 * quarter_beats[m] / (edges[m+1] - edges[m])`` per bar and writes
+a ``#BPMCHANGE`` whenever it moves.
+
+The two shipped grid builders sit at opposite ends of that contract:
+
+``generate.barscript_grid_from_trace``
+    exact, but needs an AUTHORED chart -- unavailable when serving audio.
+``generate.barscript_grid_from_bpm``
+    the deployed serving path: ``bar_sec = (240/bpm)*num/den`` tiled uniformly
+    from one scalar BPM.  It cannot express a tempo change at all, so on the
+    29.0 % of corpus charts that contain a tempo change the served grid is
+    wrong by construction and the error accumulates over the song.
+
+``barscript_grid_from_fit`` closes that gap without touching either builder or
+the decoder: ``grid.fit_grid_piecewise`` already returns ``downbeats`` that are
+NON-UNIFORM (the spliced local tempi are encoded in the spacing), so the fix is
+to hand those times through as the bar edges instead of re-tiling from
+``fit["bpm"]``.
+
+What this module does NOT do
+----------------------------
+Per-bar METER is not estimated.  ``fit_grid`` reports a single ``meter``
+(quarter beats per bar, 3 or 4, from the bar/beat period ratio), so the grid
+carries a CONSTANT ``measure_num``/``measure_den`` and ``meter_source`` is
+recorded as ``"fit_estimate"``.  A time-signature change inside the song is
+representable by the grid dict and by the TJA writer, but nothing in the
+serving stack can currently detect one from audio; claiming otherwise would be
+a fabricated ``#MEASURE``.  Variable TEMPO is supported; variable METER is not.
+"""
+
+import numpy as np
+
+# Structural sanity bounds on a single bar, expressed as the implied tempo
+# 60 * quarter_beats_per_bar / bar_seconds.  These are NOT a tempo prior: they
+# bracket what a bar can be at all.  `grid.fit_grid` only ever snaps BPM inside
+# [40, 320] and only accepts a snap within a factor 0.4-2.5 of the raw fit, so
+# [30, 400] is a strict superset of everything the estimator can emit; a bar
+# outside it is a broken fit, not a slow or fast song.  The upper bound also
+# keeps every bar far inside the decoder's WINDOW (1728 frames ~ 20.06 s), which
+# `generate_song_barscript` requires each single bar to fit in.
+GRID_MIN_BPM = 30.0
+GRID_MAX_BPM = 400.0
+
+# Bars appended past the last fitted downbeat to reach ``duration_sec``.  The
+# fit already tiles to the mel duration, so the normal case needs zero: a
+# request for more means the fit stopped early and the tail would be invented.
+MAX_TAIL_EXTRAP_BARS = 4
+
+# Splice joints in `fit_grid_piecewise` can leave one implausibly short bar
+# where a local segment hands back to the main grid (upstream only guarantees
+# a 0.3 s separation, which is below GRID_MAX_BPM at 4/4).  Dropping that single
+# barline is a bounded repair; needing it often means the downbeat sequence is
+# not a bar sequence.
+MAX_JOINT_MERGE_FRAC = 0.05
+
+SHIP_DENOM = 16  # deployed bar lattice (SOFTCHART2_RELEASE: --grid-bpm-denom 16)
+
+
+class GridFitError(ValueError):
+    """A fit cannot be turned into a well-formed bar grid.
+
+    Raised (fail-closed) for malformed downbeat sequences: non-increasing or
+    non-finite times, bar spacings outside [GRID_MIN_BPM, GRID_MAX_BPM], or a
+    fit that does not cover ``duration_sec``.  It is NOT raised for a fit that
+    is merely low-quality -- ``fit["ok"] == False`` falls back to the uniform
+    grid instead, which is a downgrade the caller can report rather than an
+    error it must handle.
+    """
+
+
+def _meter_terms(fit):
+    """(numerator, denominator) for the single estimated time signature."""
+    meter = fit.get("meter", 4)
+    if isinstance(meter, (tuple, list, np.ndarray)):
+        if len(meter) != 2:
+            raise GridFitError("fit meter must be an int or a (num, den) pair")
+        num, den = int(meter[0]), int(meter[1])
+    else:
+        num, den = int(meter), 4
+    if num <= 0 or den <= 0:
+        raise GridFitError(f"fit meter {num}/{den} must have positive terms")
+    return num, den
+
+
+def _fit_quality(fit):
+    """Fit diagnostics, JSON-ready, with the keys a raw `fit_grid` lacks."""
+    segments = fit.get("segments")
+    if segments is None:
+        segments = [(float(fit.get("phase", 0.0)), float(fit.get("bpm", 0.0)))]
+    return {
+        "ok": bool(fit.get("ok", False)),
+        "inlier_frac": (None if fit.get("inlier_frac") is None
+                        else float(fit["inlier_frac"])),
+        "rms_ms": (None if fit.get("rms_ms") is None
+                   else float(fit["rms_ms"])),
+        "n_segments": int(fit.get("n_segments", len(segments))),
+        "piecewise": bool(fit.get("piecewise", False)),
+        "bpm": float(fit.get("bpm", 0.0)),
+        "segments": [[float(t), float(b)] for t, b in segments],
+    }
+
+
+def _uniform_fallback(fit, duration_sec, num, den, denom, reason,
+                      fallback_bpm, fallback_offset, spec_version):
+    """Re-tile uniformly from a scalar BPM (the shipped serving behaviour).
+
+    This is the only path that loses tempo change, so it is always labelled
+    ``grid_source == "uniform_fallback"`` and carries ``reason``.
+    """
+    from .sc2.generate import barscript_grid_from_bpm
+
+    bpm = fallback_bpm
+    if bpm is None and fit is not None:
+        bpm = fit.get("bpm")
+    if bpm is None or not np.isfinite(float(bpm)) or float(bpm) <= 0:
+        raise GridFitError(
+            f"uniform fallback needs a usable BPM ({reason}); pass "
+            "fallback_bpm= explicitly")
+    offset = fallback_offset
+    if offset is None and fit is not None:
+        offset = fit.get("phase", 0.0)
+    offset = 0.0 if offset is None else float(offset)
+    if not np.isfinite(offset) or not 0.0 <= offset < duration_sec:
+        offset = 0.0
+    grid = barscript_grid_from_bpm(float(bpm), offset, float(duration_sec),
+                                   meter=(num, den), denom=int(denom))
+    edges = np.asarray(grid["measure_edges"], np.float64)
+    grid["grid_source"] = "uniform_fallback"
+    grid["fit_quality"] = None if fit is None else _fit_quality(fit)
+    grid["grid_meta"] = {
+        "reason": reason,
+        "n_bars": len(grid["bar_denoms"]),
+        "meter_num": int(num), "meter_den": int(den),
+        "meter_source": "fit_estimate" if fit is not None else "caller",
+        "meter_varies": False,
+        "bar_denom": int(denom),
+        "duration_sec": float(duration_sec),
+        "first_downbeat_sec": float(edges[0]),
+        "terminal_edge_sec": float(edges[-1]),
+        "tail_bars_extrapolated": 0,
+        "joint_bars_merged": 0,
+        "trailing_downbeats_dropped": 0,
+        "bar_sec_min": float(np.min(np.diff(edges))),
+        "bar_sec_max": float(np.max(np.diff(edges))),
+        "spec_labels_version": spec_version,
+    }
+    return grid
+
+
+def barscript_grid_from_fit(fit, duration_sec, *, denom=SHIP_DENOM, spec=None,
+                            require_ok=True, repair_joints=True,
+                            on_invalid="raise", fallback_bpm=None,
+                            fallback_offset=None,
+                            min_bar_bpm=GRID_MIN_BPM,
+                            max_bar_bpm=GRID_MAX_BPM):
+    """Build a BarScript supplied grid from ``grid.fit_grid_piecewise`` output.
+
+    Parameters
+    ----------
+    fit : dict or None
+        A ``fit_grid`` / ``fit_grid_fixed_bpm`` / ``fit_grid_piecewise`` result.
+        Only ``downbeats``, ``meter``, ``ok``, ``bpm`` and ``phase`` are read
+        (the rest is copied into ``fit_quality`` for display).  ``None`` means
+        beat estimation failed outright: the call falls back to the uniform
+        grid and therefore needs ``fallback_bpm``.
+    duration_sec : float
+        Audio length the grid must cover (normally ``mel.shape[1] / FPS``).
+    denom : int
+        Per-bar lattice denominator teacher-forced into the ``[BAR]`` headers,
+        uniform over the song.  Default 16 = the shipped serving decision.
+    spec : BarscriptSpec, optional
+        Not needed to build the grid (bar geometry is spec-independent); when
+        given, its ``labels_version`` is recorded in ``grid_meta`` so a served
+        grid carries the label contract it was requested under.
+    require_ok : bool
+        When True (default) a fit whose own ``ok`` gate failed is not used.
+    repair_joints : bool
+        Drop a downbeat that sits closer than one ``max_bar_bpm`` bar to its
+        predecessor (a splice-joint artefact), up to ``MAX_JOINT_MERGE_FRAC``
+        of the bars.  The LATER barline is dropped, matching the upstream
+        0.3 s de-duplication in ``fit_grid_piecewise``.
+    on_invalid : {"raise", "fallback"}
+        What to do when the downbeat sequence is malformed.  ``"raise"``
+        (default) is fail-closed; ``"fallback"`` lets a serving path degrade to
+        the uniform grid with the reason recorded instead of erroring.
+
+    Returns
+    -------
+    dict
+        The six keys the decoder consumes -- ``bpm``, ``downbeats``,
+        ``measure_edges``, ``measure_num``, ``measure_den``, ``bar_denoms`` --
+        exactly as ``barscript_grid_from_bpm`` returns them, plus three
+        provenance keys the decoder ignores:
+
+        ``grid_source``
+            ``"piecewise"``  -- bar edges ARE the fitted downbeat times, so a
+            tempo change in the fit survives into the chart and the TJA.  (The
+            name follows the producer, ``fit_grid_piecewise``; a constant-tempo
+            song takes this path too, with ``fit_quality["piecewise"] is
+            False`` and ``n_segments == 1``.)
+            ``"uniform_fallback"`` -- re-tiled from one scalar BPM; ANY tempo
+            change in the song is lost.  ``grid_meta["reason"]`` says why.
+        ``fit_quality``
+            ``{ok, inlier_frac, rms_ms, n_segments, piecewise, bpm, segments}``
+            (``None`` when ``fit is None``).
+        ``grid_meta``
+            Bar counts, meter and its source, coverage, and every repair that
+            was applied (``joint_bars_merged``, ``tail_bars_extrapolated``,
+            ``trailing_downbeats_dropped``).
+
+    Notes
+    -----
+    ``bpm`` is the fit's MAIN tempo and is display/metadata only under
+    ``"piecewise"``: the decoder reads times from ``measure_edges``, and
+    ``tja.write_tja_slots`` uses it solely for the header ``BPM:`` field before
+    emitting per-bar ``#BPMCHANGE`` from the edges.
+    """
+    if on_invalid not in ("raise", "fallback"):
+        raise ValueError("on_invalid must be 'raise' or 'fallback'")
+    duration_sec = float(duration_sec)
+    if not np.isfinite(duration_sec) or duration_sec <= 0:
+        raise ValueError("duration_sec must be finite and positive")
+    from .sc2.vocab import MAX_BAR_DENOM
+    if (isinstance(denom, bool) or not isinstance(denom, (int, np.integer))
+            or not 1 <= int(denom) <= MAX_BAR_DENOM):
+        raise ValueError(f"denom must be an int in [1, {MAX_BAR_DENOM}]")
+    denom = int(denom)
+    if not np.isfinite(min_bar_bpm) or not np.isfinite(max_bar_bpm) \
+            or not 0 < min_bar_bpm < max_bar_bpm:
+        raise ValueError("min_bar_bpm/max_bar_bpm must satisfy 0 < min < max")
+
+    spec_version = None
+    if spec is not None:
+        spec_version = getattr(spec, "labels_version", None)
+        if spec_version is None:
+            raise ValueError("spec must be a BarscriptSpec (no labels_version)")
+
+    if fit is None:
+        return _uniform_fallback(None, duration_sec, 4, 4, denom,
+                                 "beat fit unavailable", fallback_bpm,
+                                 fallback_offset, spec_version)
+    num, den = _meter_terms(fit)
+    quarter_beats = 4.0 * num / den
+    min_bar_sec = 60.0 * quarter_beats / max_bar_bpm
+    max_bar_sec = 60.0 * quarter_beats / min_bar_bpm
+
+    if require_ok and not bool(fit.get("ok", False)):
+        return _uniform_fallback(
+            fit, duration_sec, num, den, denom,
+            "fit.ok is False (inlier_frac "
+            f"{fit.get('inlier_frac')!r}, rms_ms {fit.get('rms_ms')!r})",
+            fallback_bpm, fallback_offset, spec_version)
+
+    def _bail(reason):
+        if on_invalid == "raise":
+            raise GridFitError(reason)
+        return _uniform_fallback(fit, duration_sec, num, den, denom, reason,
+                                 fallback_bpm, fallback_offset, spec_version)
+
+    raw_db = fit.get("downbeats")
+    if raw_db is None:
+        return _bail("fit has no 'downbeats'")
+    try:
+        db = np.asarray(raw_db, dtype=np.float64).reshape(-1)
+    except (TypeError, ValueError) as e:
+        return _bail(f"fit downbeats are not a float array: {e}")
+    if db.size < 2:
+        return _bail(f"fit has {db.size} downbeat(s); at least 2 are needed "
+                     "to establish a bar period")
+    if not np.all(np.isfinite(db)):
+        return _bail("fit downbeats contain non-finite times")
+    if np.any(np.diff(db) <= 0):
+        bad = int(np.argmax(np.diff(db) <= 0))
+        return _bail(f"fit downbeats are not strictly increasing at index "
+                     f"{bad} ({db[bad]:.6f} -> {db[bad + 1]:.6f})")
+    if db[0] < 0:
+        return _bail(f"first downbeat {db[0]:.6f}s is negative")
+    if db[0] >= duration_sec:
+        return _bail(f"first downbeat {db[0]:.6f}s is at or past the audio end "
+                     f"({duration_sec:.6f}s)")
+    if db[0] > max_bar_sec:
+        return _bail(f"first downbeat {db[0]:.6f}s leaves an unbarred head "
+                     f"longer than one bar ({max_bar_sec:.6f}s)")
+
+    # trailing downbeats past the requested duration: the caller's duration is
+    # authoritative for what has to be charted
+    n_trailing = int(np.count_nonzero(db >= duration_sec))
+    if n_trailing:
+        db = db[db < duration_sec]
+        if db.size < 2:
+            return _bail("fewer than 2 downbeats remain inside duration_sec")
+
+    # splice-joint repair (drop the LATER barline of an impossibly short bar)
+    n_merged = 0
+    if repair_joints:
+        keep = [0]
+        for i in range(1, db.size):
+            if db[i] - db[keep[-1]] < min_bar_sec:
+                n_merged += 1
+                continue
+            keep.append(i)
+        if n_merged:
+            limit = max(1, int(np.floor(MAX_JOINT_MERGE_FRAC * db.size)))
+            if n_merged > limit:
+                return _bail(
+                    f"{n_merged} of {db.size} downbeats sit closer than one "
+                    f"{max_bar_bpm:g} BPM bar ({min_bar_sec * 1e3:.1f} ms); "
+                    f"above the {limit}-bar joint-repair budget this is not a "
+                    "bar sequence")
+            if len(keep) < 2:
+                return _bail("joint repair left fewer than 2 downbeats")
+            db = db[np.asarray(keep)]
+
+    # terminal edge + tail: extend at the LAST observed bar period.  The bar
+    # after the final downbeat is the only extrapolated one in the normal case;
+    # anything beyond that is counted and budgeted.
+    tail_period = float(db[-1] - db[-2])
+    edges = list(db)
+    edges.append(edges[-1] + tail_period)
+    n_tail = 0
+    while edges[-1] < duration_sec - 1e-9:
+        if n_tail >= MAX_TAIL_EXTRAP_BARS:
+            covered = (edges[-1] - float(db[0])) / max(duration_sec, 1e-9)
+            return _bail(
+                f"fit covers only {covered * 100:.1f}% of the audio; "
+                f"reaching {duration_sec:.3f}s would take more than "
+                f"{MAX_TAIL_EXTRAP_BARS} extrapolated bars")
+        edges.append(edges[-1] + tail_period)
+        n_tail += 1
+    edges = np.asarray(edges, dtype=np.float64)
+
+    bar_sec = np.diff(edges)
+    if np.any(bar_sec <= 0):
+        return _bail("bar edges are not strictly increasing after repair")
+    too_short = np.flatnonzero(bar_sec < min_bar_sec - 1e-12)
+    if too_short.size:
+        i = int(too_short[0])
+        return _bail(
+            f"bar {i} lasts {bar_sec[i] * 1e3:.1f} ms -> "
+            f"{60.0 * quarter_beats / bar_sec[i]:.1f} BPM, above the "
+            f"{max_bar_bpm:g} BPM structural bound "
+            f"({too_short.size} bar(s) affected)")
+    too_long = np.flatnonzero(bar_sec > max_bar_sec + 1e-12)
+    if too_long.size:
+        i = int(too_long[0])
+        return _bail(
+            f"bar {i} lasts {bar_sec[i]:.3f} s -> "
+            f"{60.0 * quarter_beats / bar_sec[i]:.1f} BPM, below the "
+            f"{min_bar_bpm:g} BPM structural bound "
+            f"({too_long.size} bar(s) affected)")
+
+    n_bars = len(edges) - 1
+    grid = {
+        "bpm": float(fit.get("bpm", 60.0 * quarter_beats / float(np.median(bar_sec)))),
+        "downbeats": edges[:-1],
+        "measure_edges": edges,
+        "measure_num": [int(num)] * n_bars,
+        "measure_den": [int(den)] * n_bars,
+        "bar_denoms": [denom] * n_bars,
+        "grid_source": "piecewise",
+        "fit_quality": _fit_quality(fit),
+        "grid_meta": {
+            "reason": None,
+            "n_bars": n_bars,
+            "meter_num": int(num), "meter_den": int(den),
+            # single estimated time signature: per-bar meter is NOT estimable
+            # from audio in this stack (see the module docstring)
+            "meter_source": "fit_estimate",
+            "meter_varies": False,
+            "bar_denom": denom,
+            "duration_sec": duration_sec,
+            "first_downbeat_sec": float(edges[0]),
+            "terminal_edge_sec": float(edges[-1]),
+            "tail_bars_extrapolated": int(n_tail),
+            "joint_bars_merged": int(n_merged),
+            "trailing_downbeats_dropped": int(n_trailing),
+            "bar_sec_min": float(bar_sec.min()),
+            "bar_sec_max": float(bar_sec.max()),
+            "bar_bpm_min": float(60.0 * quarter_beats / bar_sec.max()),
+            "bar_bpm_max": float(60.0 * quarter_beats / bar_sec.min()),
+            "n_distinct_bar_sec": int(
+                np.unique(np.round(bar_sec, 6)).size),
+            "spec_labels_version": spec_version,
+        },
+    }
+    if not np.isfinite(grid["bpm"]) or grid["bpm"] <= 0:
+        grid["bpm"] = float(60.0 * quarter_beats / float(np.median(bar_sec)))
+    return grid
+
+
+def describe_grid(grid):
+    """One honest line about where a served grid came from, for logs and UI."""
+    meta = grid.get("grid_meta") or {}
+    q = grid.get("fit_quality")
+    src = grid.get("grid_source", "unknown")
+    n = meta.get("n_bars", len(grid.get("bar_denoms", [])))
+    head = (f"{n} bars, {meta.get('meter_num', '?')}/{meta.get('meter_den', '?')} "
+            f"(estimated, constant)")
+    if src == "piecewise":
+        rng = (f"{meta.get('bar_bpm_min', float('nan')):.1f}-"
+               f"{meta.get('bar_bpm_max', float('nan')):.1f} BPM")
+        detail = (f"grid from estimated barlines, {rng} across bars, "
+                  f"{q['n_segments']} tempo segment(s)" if q else
+                  "grid from estimated barlines")
+        if meta.get("joint_bars_merged"):
+            detail += f", {meta['joint_bars_merged']} joint bar(s) merged"
+        if meta.get("tail_bars_extrapolated"):
+            detail += f", {meta['tail_bars_extrapolated']} tail bar(s) extrapolated"
+    else:
+        detail = (f"UNIFORM {grid['bpm']:.2f} BPM fallback -- tempo changes are "
+                  f"not represented ({meta.get('reason')})")
+    if q is not None:
+        inl = "n/a" if q["inlier_frac"] is None else format(q["inlier_frac"], ".3f")
+        rms = "n/a" if q["rms_ms"] is None else format(q["rms_ms"], ".1f") + "ms"
+        detail += f" [fit ok={q['ok']}, inlier={inl}, rms={rms}]"
+    return f"{head}; {detail}"

softchart/sc2_loader.py

@@ -21,14 +21,30 @@ unaudited contract.  ``serving_kwargs`` therefore mirrors the package's own
 ``scripts/sc2_package.py:serving_kwargs`` and passes the recorded values
 explicitly into the decoder rather than letting module defaults apply.
 
-Deployment grid: a uniform ``/16`` lattice synthesized from user BPM and
-offset, decoded with ``bar_denoms='supplied'`` -- the ``SHIP_DECISION``
-ruling, and the ``default`` serving profile.  The package also carries a
-``deploy_bpm_grid`` profile (model-emitted denominators masked to divisors of
-96); the model card does NOT recommend it for this checkpoint (§2.8).  A
-``/16`` grid makes triplets arithmetically impossible: 3 does not divide 16.
-
-The returned dict always reports the grid that was actually used.
+Deployment grid: a ``/16`` bar-local lattice decoded with
+``bar_denoms='supplied'`` -- the ``SHIP_DECISION`` ruling, and the ``default``
+serving profile.  The package also carries a ``deploy_bpm_grid`` profile
+(model-emitted denominators masked to divisors of 96); the model card does NOT
+recommend it for this checkpoint (§2.8).  A ``/16`` grid makes triplets
+arithmetically impossible: 3 does not divide 16.
+
+Two things called "grid" meet here and must not be confused.  ``/16`` is the
+BAR-LOCAL lattice: how finely a note may be placed inside one bar.  The BAR
+TIMELINE -- where each barline falls in the audio -- is a separate object, and
+``generate`` accepts it two ways:
+
+``bpm=`` + ``offset_sec=``
+    the grid is synthesized as a uniform tiling, ``bar_sec = (240/bpm)*num/den``
+    from the first downbeat.  One scalar tempo for the whole song; a tempo
+    change cannot be expressed.
+``grid=``
+    a caller-built supplied grid whose ``measure_edges`` are used verbatim.
+    ``softchart.barscript_grid.barscript_grid_from_fit`` builds one from an
+    estimated beat fit, so non-uniform barlines (and therefore tempo change)
+    survive into both the decode and the ``#BPMCHANGE`` lines of the TJA.
+
+The returned dict always reports the grid that was actually used, including
+which of the two routes produced it.
 """
 
 from __future__ import annotations
@@ -39,6 +55,7 @@ import os
 import re
 import threading
 
+import numpy as np
 import torch
 
 from .sc2 import generate as sc2_generate
@@ -554,6 +571,84 @@ def serving_kwargs(config, profile="default"):
     }
 
 
+# ---------------------------------------------------------------------------
+# supplied bar timelines
+
+
+SUPPLIED_GRID_KEYS = ("bpm", "downbeats", "measure_edges", "measure_num",
+                      "measure_den", "bar_denoms")
+
+
+def _check_supplied_grid(grid, grid_denom):
+    """Shape-check a caller-built supplied grid before it reaches the decoder.
+
+    The decoder's own ``generate._barscript_grid`` validates the geometry
+    (edges increasing, one edge per bar plus the terminal one, denominators in
+    range) and is the authority on it, so this does not duplicate that work.
+    What it adds is the check the decoder cannot make: that ``grid_denom`` --
+    the lattice the CALLER believes it is serving, and the number reported to
+    the user -- actually agrees with the denominators in the grid.  A grid
+    built for a different lattice than the one being advertised would decode
+    fine and be described wrongly.
+    """
+    if not isinstance(grid, dict):
+        raise ValueError("grid must be a dict")
+    missing = [k for k in SUPPLIED_GRID_KEYS if k not in grid]
+    if missing:
+        raise ValueError(f"supplied grid is missing {missing}; a BarScript "
+                         f"grid needs {list(SUPPLIED_GRID_KEYS)}")
+    denoms = [int(d) for d in grid["bar_denoms"]]
+    if not denoms:
+        raise ValueError("supplied grid has no bars")
+    if grid_denom is not None and set(denoms) != {int(grid_denom)}:
+        raise ValueError(
+            f"supplied grid carries bar_denoms {sorted(set(denoms))} but "
+            f"grid_denom={int(grid_denom)} was requested; pass "
+            "grid_denom=None to serve a grid whose lattice varies per bar")
+    return grid
+
+
+def _supplied_grid_info(grid, duration_sec):
+    """Provenance for a supplied grid, including whether tempo actually varies.
+
+    ``n_distinct_bar_sec`` is the load-bearing field: a supplied grid is the
+    only route that CAN carry a tempo change, but taking it does not mean a
+    change was found.  Bar lengths are compared at microsecond resolution --
+    the same rounding ``barscript_grid.barscript_grid_from_fit`` records -- so
+    a grid that is uniform to within float noise reports one distinct length.
+    """
+    edges = np.asarray(grid["measure_edges"], dtype=np.float64)
+    bar_sec = np.diff(edges)
+    quarter = np.asarray([4.0 * int(n) / int(d) for n, d in
+                          zip(grid["measure_num"], grid["measure_den"])],
+                         dtype=np.float64)
+    bar_bpm = 60.0 * quarter / bar_sec
+    denoms = [int(d) for d in grid["bar_denoms"]]
+    meters = sorted({(int(n), int(d)) for n, d in
+                     zip(grid["measure_num"], grid["measure_den"])})
+    info = {
+        "source": "supplied",
+        "denom": denoms[0] if len(set(denoms)) == 1 else None,
+        "bpm": float(grid["bpm"]),
+        "offset_sec": float(edges[0]),
+        "duration_sec": float(duration_sec),
+        "meter": [meters[0][0], meters[0][1]],
+        "meter_varies": len(meters) > 1,
+        "n_bars": len(denoms),
+        "triplets_representable": all(d % 3 == 0 for d in denoms),
+        "n_distinct_bar_sec": int(np.unique(np.round(bar_sec, 6)).size),
+        "bar_bpm_min": float(bar_bpm.min()),
+        "bar_bpm_max": float(bar_bpm.max()),
+        "terminal_edge_sec": float(edges[-1]),
+    }
+    # provenance the grid builder attached, carried through untouched so the
+    # caller does not have to hold on to the builder's return value
+    for key in ("grid_source", "fit_quality", "grid_meta"):
+        if key in grid:
+            info[key] = grid[key]
+    return info
+
+
 class MotifConstraint:
     """Serve the motif-hard value the package RESOLVED, not a module default.
 
@@ -752,8 +847,9 @@ class SoftChart2:
 
     # -- generation -------------------------------------------------------
 
-    def generate(self, mel, course, level=None, *, bpm,
-                 offset_sec=0.0, duration_sec=None, density_bucket=None,
+    def generate(self, mel, course, level=None, *, bpm=None,
+                 offset_sec=0.0, duration_sec=None, grid=None,
+                 density_bucket=None,
                  density_nps=None, meter=(4, 4), grid_denom=SHIP_GRID_DENOM,
                  seed=0, big_rate=None, span_rate=None, stream=None,
                  sync_band=None, title="SoftChart", wave="song.ogg",
@@ -766,14 +862,26 @@ class SoftChart2:
         ``course``   one of ``COURSES`` (easy/normal/hard/oni/ura), or ``None``
                      to decode unconditioned.
         ``level``    TJA level, clamped to 1..12 by the prefix builder.
-        ``bpm``      tempo of the synthesized grid.
+        ``bpm``      tempo of the SYNTHESIZED grid.  Mutually exclusive with
+                     ``grid``; exactly one of the two must be given.
         ``offset_sec``  audio time of the FIRST DOWNBEAT, in seconds.  This is
-                     the negative of the TJA ``OFFSET`` field.
+                     the negative of the TJA ``OFFSET`` field.  Only meaningful
+                     on the ``bpm`` route.
+        ``grid``     a ready-made supplied grid -- ``{bpm, downbeats,
+                     measure_edges, measure_num, measure_den, bar_denoms}`` --
+                     used VERBATIM instead of tiling one from ``bpm``.  This is
+                     the route that can carry a tempo change: the decoder and
+                     ``write_tja_slots`` both read bar times out of
+                     ``measure_edges``, so non-uniform bars stay non-uniform.
+                     Build one with
+                     ``softchart.barscript_grid.barscript_grid_from_fit``.
         ``duration_sec``  defaults to ``mel.shape[1] / FPS``.
         ``density_bucket`` DENS bucket 0..15, or ``density_nps`` in notes per
                      second, which is bucketed with the package's width.
         ``grid_denom``  bar-local lattice denominator teacher-forced into every
-                     [BAR] header.  16 is the shipped deployment grid.
+                     [BAR] header.  16 is the shipped deployment grid.  With a
+                     supplied ``grid`` the grid's own ``bar_denoms`` govern and
+                     ``grid_denom`` is only cross-checked against them.
         ``overrides``  serving parameters (``temperature``, ``top_p``,
                      ``min_onset_gap_sec``, ...).  The package's recorded
                      values apply unless one is named here; anything overridden
@@ -797,6 +905,10 @@ class SoftChart2:
         course = None if course is None else str(course).lower()
         if mel.ndim != 2:
             raise ValueError("mel must be (n_mels, T)")
+        if (bpm is None) == (grid is None):
+            raise ValueError(
+                "pass exactly one of bpm= (synthesize a uniform grid) or "
+                "grid= (use a supplied grid verbatim)")
         if duration_sec is None:
             duration_sec = mel.shape[1] / FPS
         if density_bucket is None and density_nps is not None:
@@ -814,22 +926,26 @@ class SoftChart2:
                    if k in kwargs and v is not None and v != kwargs[k]}
         kwargs.update({k: v for k, v in overrides.items() if v is not None})
 
-        grid = barscript_grid_from_bpm(bpm, float(offset_sec),
-                                       float(duration_sec), meter=meter,
-                                       denom=int(grid_denom))
-        grid_info = {
-            "source": "bpm",
-            "denom": int(grid_denom),
-            "bpm": float(bpm),
-            "offset_sec": float(offset_sec),
-            "duration_sec": float(duration_sec),
-            "meter": [int(meter[0]), int(meter[1])],
-            "n_bars": len(grid["bar_denoms"]),
-            "bar_denoms": kwargs["bar_denoms"],
-            "bar_denom_mask": kwargs["bar_denom_mask"],
-            "triplets_representable": (int(grid_denom) % 3 == 0),
-            "profile": profile,
-        }
+        if grid is None:
+            grid = barscript_grid_from_bpm(bpm, float(offset_sec),
+                                           float(duration_sec), meter=meter,
+                                           denom=int(grid_denom))
+            grid_info = {
+                "source": "bpm",
+                "denom": int(grid_denom),
+                "bpm": float(bpm),
+                "offset_sec": float(offset_sec),
+                "duration_sec": float(duration_sec),
+                "meter": [int(meter[0]), int(meter[1])],
+                "n_bars": len(grid["bar_denoms"]),
+                "triplets_representable": (int(grid_denom) % 3 == 0),
+            }
+        else:
+            grid = _check_supplied_grid(grid, grid_denom)
+            grid_info = _supplied_grid_info(grid, float(duration_sec))
+        grid_info["bar_denoms"] = kwargs["bar_denoms"]
+        grid_info["bar_denom_mask"] = kwargs["bar_denom_mask"]
+        grid_info["profile"] = profile
 
         # config.serving_basis: span_bucket0_profile is null in this release
         # and is a KNOWN GAP (§2.7), not a tuned choice. A package that ever

static/app.css

@@ -1299,6 +1299,22 @@ audio {
   font-weight: 760;
 }
 
+/* Sentence-valued metrics (the bar timeline report). They take the whole row
+   and wrap, because a truncated "tempo changes are NOT represented" would be
+   worse than not showing it at all. */
+.metric--wide {
+  grid-column: 1 / -1;
+}
+
+.metric--wide dd {
+  overflow: visible;
+  font-size: 12.5px;
+  font-weight: 620;
+  line-height: 1.5;
+  text-overflow: clip;
+  white-space: normal;
+}
+
 .preview-tabs {
   display: flex;
   gap: 20px;

static/app.js

@@ -127,9 +127,22 @@ const metricLabels = {
   grid_anchor: "Grid anchor",
   density_bucket: "Density bucket",
   sampling: "Sampling",
-  tempo_map: "Tempo map"
+  // The bar timeline: where the barlines fell, whether the song's tempo change
+  // survived into them, and how well the beat fit did. The server sends these
+  // as finished sentences -- the interface must not restate or soften them.
+  // They come last so the full-width rows land under the compact tiles.
+  beat_fit: "Beat fit",
+  bar_grid: "Bar grid",
+  tempo_map: "Tempo map",
+  grid_repairs: "Grid repairs"
 };
 
+// Metrics whose value is a sentence rather than a number or a short label.
+// A compact tile would ellipsis them away, and these are exactly the ones a
+// user has to be able to read: whether this song's tempo change was handled.
+const wideMetrics = new Set(["beat_fit", "bar_grid", "tempo_map",
+                             "grid_repairs"]);
+
 // Filled from /api/capabilities: the server owns the model list and the model
 // card's limitation text, so the interface never restates either from memory.
 let capabilities = null;
@@ -435,7 +448,11 @@ function metricValue(key, value) {
   if (typeof value === "boolean") return value ? "Yes" : "No";
   if (typeof value === "number") return Number.isInteger(value) ? String(value) : value.toFixed(2);
   if (typeof value === "object") return JSON.stringify(value);
-  return String(value).replaceAll("_", " ");
+  // Underscores are prettified only in single-token enum values. Sentences
+  // from the server quote identifiers verbatim (`inlier_frac`, `rms_ms`, a
+  // fit's own reason string); rewriting those would misquote the server.
+  const text = String(value);
+  return text.includes(" ") ? text : text.replaceAll("_", " ");
 }
 
 function renderMetrics(metrics) {
@@ -455,7 +472,7 @@ function renderMetrics(metrics) {
     const wrapper = document.createElement("div");
     const term = document.createElement("dt");
     const description = document.createElement("dd");
-    wrapper.className = "metric";
+    wrapper.className = wideMetrics.has(key) ? "metric metric--wide" : "metric";
     term.textContent = label;
     description.textContent = metricValue(key, value);
     description.title = description.textContent;