Upstream Sync

Syncing with upstream acestep.cpp

When to use this skill

• Pulling new commits from upstream acestep.cpp (https://github.com/ServeurpersoCom/acestep.cpp) into this fork's engine/.
• Checking whether a sync is pending, or repairing a botched one.
• Diagnosing: linker error unresolved external symbol hotstep_sampler_linked_, or a build that compiles clean but all solvers/schedulers/guidance modes stopped working.

Background you need (no prior context assumed): The C++ engine in engine/ is a fork of acestep.cpp, a GGML port of the ACE-Step music model. The generation pipeline is LM → DiT → VAE, where DiT = Diffusion Transformer, the denoising model. HOT-Step replaces upstream's DiT sampling loop (dit-sampler.h) with its own (hot-step-sampler.h) that adds 17 solvers, 9 schedulers, guidance modes, and Lua plugins. The fork is not a git merge — it is file-copy based, using three zones:

⚠ Zone model drift (verified 2026-07-14): two of this table's assumptions no longer hold.

1. src/solvers/ now EXISTS upstream (added 2026-05-06, commit 8974778 — modular Euler/SDE/DPM++3M/STORK4 dispatch). Its 7 filenames collide with the fork's own engine/src/solvers/ (created independently 2026-04-18, commit 889c250, different interface). The Phase 2 copy loop MUST also exclude everything under src/solvers/ — a direct copy clobbers HOT-Step's native solvers with incompatible upstream versions.
2. The Upstream Zone has eroded. As of 2026-07-14, 11 of the 13 upstream-touched files since 31cc9ea are fork-modified (e.g. qwen3-lm.h carries safetensors loading via fork-only weight-source.h/config-json.h; backend.h, dit-graph.h, vae.h, request.*, wav.h, qwen3-enc.h, pipeline-synth.* also differ). Do NOT assume direct-copy safety from this table — before copying any file, verify pristineness: diff the fork's copy against git show <lastSynced>:src/<file> from the upstream clone (with --strip-trailing-cr). Pristine → copy; modified → manual merge.

engine/tools/ace-server.cpp is upstream's server kept as a direct-copy reference only — not compiled. The shipped ace-server binary is built from engine/tools/hot-step-server.cpp (see engine/CMakeLists.txt:416-418).

The full workflow doc lives at docs/plans/upstream-sync-workflow.md, which is gitignored (local-only) — other machines will not have it. This skill is the portable distillation, with two known errors in that doc corrected (see reference.md).

ggml is not part of this sync

acestep.cpp pins its own ggml (ServeurpersoCom/ggml). HOT-Step does not follow that pin: engine/ggml is pinned to HOT-ggml's hot-step-neutral branch, which is ggml-org master plus HOT-Step's ggml changes as commits (docs/dev/ggml-fork.md). Copying acestep.cpp files never touches engine/ggml. If a synced file needs a newer ggml op or fix, land it on HOT-ggml first (cherry-pick from ServeurpersoCom/ggml or ggml-org), then move the gitlink, then rerun engine/verify-hooks.ps1 (hooks 7-17 cover the fork).

Golden rules (hard constraints)

1. NEVER direct-copy the 3 Modified Upstream Zone files (pipeline-synth-ops.cpp, model-store.h, dit.h). WHY: copying pipeline-synth-ops.cpp wholesale is the silent failure — it compiles clean but kills every HOT-Step sampler feature (see hook table below). This actually happened once; the whole defense system exists because of it.
2. ALWAYS run engine/verify-hooks.ps1 after copying files and BEFORE building. WHY: it catches hook loss in seconds; a build wastes minutes and a silent regression wastes hours.
3. Commit the fork locally before starting. WHY: file-copy sync has no git-merge undo; the commit is your only rollback point.
4. NEVER push the v1.5-upstream-sync-* tag (or anything without explicit user approval). WHY: any pushed v* tag triggers the full multi-platform CI release build. The tag is fine locally.
5. Rebuild via dev-rebuild.bat at repo root, NEVER engine/build.cmd directly. WHY: the app may be running without you knowing (you cannot reliably tell); the Node server auto-respawns ace-server on crash → infinite respawn + file-lock loop. dev-rebuild.bat handles clean shutdown and is a safe no-op when nothing is running. It does not relaunch the app afterwards: start it again with dev.bat (detached) and check http://localhost:3000.
6. NEVER cmake --build . --clean-first. WHY: CUDA kernel recompile is 20+ min. Stale .obj? Delete only engine/build/acestep-core.dir/ and engine/build/Release/acestep-core.lib.
7. Never add HOT-Step code to Upstream Zone files (new behavior goes in a hot-step-* file), and never add hot-step-* files to the upstream clone. WHY: keeps future syncs a trivial copy.
8. Git hygiene: all work on master, stage explicit paths only, never git add -A.

The three hook files (verified line numbers)

Why the sampler hook failure is silent: the hook is a substitution, not an addition. Upstream dit-sampler.h and fork hot-step-sampler.h both provide a function named dit_ggml_generate. A whole-file copy of upstream pipeline-synth-ops.cpp replaces both the include AND the call site (pipeline-synth-ops.cpp:1503) with mutually-consistent upstream versions — everything compiles, HOT-Step's sampler simply stops being called.

The defense — linker sentinel: engine/src/hot-step-sampler.h:1312 defines external-linkage symbol hotstep_sampler_linked_; engine/tools/hot-step-server.cpp:51-52 references it. If the include reverts to dit-sampler.h, the symbol vanishes and the link fails with unresolved external symbol hotstep_sampler_linked_. That exact error means: re-hook hot-step-sampler.h in pipeline-synth-ops.cpp. Mechanism detail: reference.md.

verify-hooks.ps1

powershell -File "D:\Ace-Step-Latest\hot-step-cpp\engine\verify-hooks.ps1"

Exit 0 = intact, exit 1 = broken. It runs 5 checks (not 3 — the script is authoritative over the docs): the three hook files above, plus hot-step-server.cpp → hot-step-params.h include, plus the sentinel string in hot-step-sampler.h (engine/verify-hooks.ps1:15-68).

The sync procedure

Prerequisite: fork committed locally (Rule 3). The vanilla upstream clone lives at D:\Ace-Step-Latest\acestepcpp\acestep.cpp (a separate repo; if this machine lacks it, git clone https://github.com/ServeurpersoCom/acestep.cpp there first).

Phase 1 — Fetch and assess

git -C D:\Ace-Step-Latest\acestepcpp\acestep.cpp pull origin master

Read the last-synced commit from the marker. The marker uses KEY=VALUE lines — parse the UPSTREAM_COMMIT= line (the workflow doc's "first non-comment line" snippet is WRONG for this format):

$lastSynced = ((Get-Content "D:\Ace-Step-Latest\hot-step-cpp\engine\UPSTREAM_SYNC" | Where-Object { $_ -match '^UPSTREAM_COMMIT=' }) -replace '^UPSTREAM_COMMIT=','').Trim()
git -C D:\Ace-Step-Latest\acestepcpp\acestep.cpp log --oneline "$lastSynced..HEAD" -- src/ tools/ace-server.cpp
git -C D:\Ace-Step-Latest\acestepcpp\acestep.cpp diff --stat "$lastSynced..HEAD" -- src/ tools/ace-server.cpp

Zero commits → already up to date, stop.

Phase 2 — Direct-copy Upstream Zone files (with hard exclusions)

cd D:\Ace-Step-Latest\acestepcpp\acestep.cpp
$excludeFiles = @("pipeline-synth-ops.cpp", "model-store.h", "dit.h")   # NEVER direct-copy
$changedFiles = git diff --name-only "$lastSynced..HEAD" -- src/
foreach ($f in $changedFiles) {
    $basename = Split-Path $f -Leaf
    if ($excludeFiles -contains $basename) {
        Write-Host "SKIP (modified upstream): $f — manual merge in Phase 3" -ForegroundColor Yellow
        continue
    }
    Copy-Item "D:\Ace-Step-Latest\acestepcpp\acestep.cpp\$f" "D:\Ace-Step-Latest\hot-step-cpp\engine\$f" -Force
    Write-Output "Copied: $f"
}
# New upstream files — any new .cpp needs an engine/CMakeLists.txt entry:
git diff --diff-filter=A --name-only "$lastSynced..HEAD" -- src/

Do NOT copy upstream src/dit-sampler.h expecting it to matter — the fork's engine/src/dit-sampler.h is dead code (nothing compiled includes it; the active sampler is hot-step-sampler.h). Copying it is harmless but see Phase 4.

Phase 3 — Manual-merge the Modified Upstream Zone

cd D:\Ace-Step-Latest\acestepcpp\acestep.cpp
foreach ($f in @("src/pipeline-synth-ops.cpp", "src/model-store.h", "src/dit.h")) {
    if (git log --oneline "$lastSynced..HEAD" -- $f) { Write-Host "NEEDS MERGE: $f" -ForegroundColor Yellow }
}

For each flagged file: review git diff $lastSynced..HEAD -- src/<file> in the upstream clone, then hand-port those changes into the fork's copy without removing the hooks:

• pipeline-synth-ops.cpp: keep the fork-only includes (lines 9–12) and the fork's extended dit_ggml_generate call site (line 1503). This file has diverged well beyond the include line — treat the fork's copy as the base and port upstream's diff into it, never the reverse.
• dit.h: keep the includes at lines 11–13 (adapter-merge.h, hot-step-build-flags.h, adapter-runtime.h).
• model-store.h: keep the hot-step-params.h include (line 53).

Phase 4 — Port fixes from upstream dit-sampler.h

git -C D:\Ace-Step-Latest\acestepcpp\acestep.cpp log --oneline "$lastSynced..HEAD" -- src/dit-sampler.h

If changed: review the diff and hand-port relevant bug fixes into engine/src/hot-step-sampler.h. Do NOT overwrite hot-step-sampler.h with upstream's file. If upstream changed the dit_ggml_generate signature, update both the fork's signature in hot-step-sampler.h (a superset with extra params) and the call site in pipeline-synth-ops.cpp:1503 to stay compatible.