numchuck 0.2.0__tar.gz → 0.2.1__tar.gz

{numchuck-0.2.0 → numchuck-0.2.1}/CHANGELOG.md

@@ -15,6 +15,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 
+### Fixed
+
+- **A new ChucK instance inherited a destroyed one's taps** (`src/_numchuck.cpp`): Tap slots are keyed by the instance pointer, and the allocator hands a destroyed instance's address straight to the next one. An instance released by the garbage collector never runs the shutdown path that deactivates its slots, so its registrations outlived it and were adopted by whichever instance landed on that address -- measured at 18 of 20 attempts. `list_taps()` reported a tap the caller never registered, and during real-time audio `get_ugen_samples()` would have served that stale ring instead of refusing the read. Construction now releases everything keyed to the address it claims, and `init()` does the same for the shred watcher, which is keyed by the VM pointer and equally reusable. The tap slot's owner became atomic, since it is now cleared while the audio thread may be scanning slots. Caught by CI on macOS x86_64: a tap leaked from one test surfaced as a stale name several tests later, on a run whose test filter changed the allocation pattern enough to reuse the address. The pointer-keyed chout/cherr maps are cleared by the same path; they were stale but unreachable, because their C++ hook has to be installed on each instance separately.
+
+## [0.2.1]
+
+### Added
+
+- **Global UGen sample tap** (`src/_numchuck.cpp`, `api.py`): `ChucK.get_ugen_samples(name, num_frames, num_channels=1)` and `Chuck.ugen_samples(...)` read the most recent samples from a named `global UGen`, which taps audio mid-graph rather than the summed dac output that `run()` returns. Returns a float32 array, 1-D for mono and channel-major `(channels, frames)` otherwise, matching ChucK's non-interleaved multichannel layout. The ChucK side must enable buffering first (`1 => tap.buffered;`), otherwise ChucK fills the buffer with zeros.
+
+- **Race-free tap capture during real-time audio** (`src/_numchuck.cpp`, `api.py`): `add_tap(name, num_channels, capacity_frames)`, `remove_tap(name)` and `list_taps()`, with `Chuck.add_tap()` / `remove_tap()` / `taps`. Reading a UGen buffer from Python while the audio thread writes it is a data race -- `Chuck_UGen` keeps an 8192-sample `AccumBuffer` whose write offset is a plain integer and whose `get_most_recent()` memcpy's with no synchronization. Measured on a pure sine: 831 of 274,240 reads of the full ring came back spliced (0.3%), with discontinuities up to 9x the waveform's own maximum sample-to-sample step; smaller reads had ring headroom and showed none. A registered tap is instead sampled on the audio thread immediately after `chuck->run()` returns, when nothing else is writing, and appended to a per-tap ring published under a seqlock, so the audio thread never blocks and a colliding reader retries rather than returning spliced data. The same measurement through a tap: zero torn reads in 1.2 million. Taps also accumulate history across callbacks, so reads are not limited to one audio block. While real-time audio is running, reading an unregistered UGen now raises with a message pointing at `add_tap()` instead of silently returning possibly-torn data; offline reads are unchanged, since the VM only advances inside `run()`, which holds the GIL.
+
+- **Abort the running shred** (`src/_numchuck.cpp`, `api.py`): `ChucK.abort_current_shred()` and `Chuck.abort_shred()` flag the shred currently executing in the VM. This is the only way to break out of a shred stuck in a loop that never advances time, which `remove_shred` cannot reach. The VM only has a current shred while inside a compute cycle, so this applies during real-time audio, called from another thread; it returns `False` when there is nothing to abort.
+
+- **Shred lifecycle watcher** (`src/_numchuck.cpp`, `api.py`, `__init__.py`): `ChucK.subscribe_shred_watcher(callback, options)` / `remove_shred_watcher()` and `Chuck.on_shred(callback)` deliver `(code, shred_id, name)` as shreds are sporked, removed, suspended or activated, replacing the need to poll `get_all_shred_ids()`. Subscription flags `SHRED_WATCH_SPORK`, `_REMOVE`, `_SUSPEND`, `_ACTIVATE`, `_ALL` and `_NONE` are exported from the package. One watcher per instance; it is unsubscribed on shutdown so no notification can arrive after the Python callable is dropped.
+
+- **Indexed and associative global array getters** (`src/_numchuck.cpp`, `api.py`): `get_global_int_array_value`, `get_global_float_array_value`, `get_global_associative_int_array_value` and `get_global_associative_float_array_value` complete the array API, whose setters already existed -- values written by key from Python could not previously be read back, since an associative array has no whole-array fetch. The high-level `Chuck` class gained a global-array section covering whole arrays, elements by index and entries by key (`set_int_array`/`get_int_array`, `set_int_array_value`/`get_int_array_value`, `set_assoc_int`/`get_assoc_int`, and float equivalents).
+
+- **Runtime adaptive block size** (`src/_numchuck.cpp`, `api.py`): `ChucK.set_adaptive(max_block_size)` / `get_adaptive()` and `Chuck.set_adaptive()` / `Chuck.adaptive` read and change the shreduler's adaptive block processing on a running VM. Guarded on both sides: UGens allocate their vectorized buffers when they are created (the dac, adc and bunghole during VM init), so enabling adaptive mode on a VM that started non-adaptive would run the vectorized code path over buffers that were never allocated -- a segfault -- and raising the size past what init allocated overruns them. The binding raises `RuntimeError` and `ValueError` respectively instead.
+
+- **Richer shred metadata** (`src/_numchuck.cpp`): `get_shred_info` now also reports `is_blocked` (waiting on an event), `wake_time`, `start` and the shred's `args`.
+
+### Fixed
+
+- **`vm_adaptive=True` silently did nothing** (`api.py`, `constants.py`): `PARAM_VM_ADAPTIVE` is a maximum block size, not a flag, and ChucK treats any value `<= 1` as off -- so passing `True` set it to 1 and left adaptive mode disabled. `Chuck(vm_adaptive=...)` now accepts a block size directly, with `True` selecting `DEFAULT_ADAPTIVE_BLOCK_SIZE` (512), and the `vm_adaptive` property reports whether the size actually enables the mode.
+
 ## [0.2.0]
 
 ### Changed
@@ -25,6 +51,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Fixed
 
+- **Wheels rejected by PyPI's RECORD check: directory entries in the archive** (`scripts/repair_wheel.py`, `scripts/check_wheel_record.py`): Built wheels contained ZIP directory entries (`numchuck/`, `numchuck/tui/`, ...) that were also listed in RECORD with the empty-content hash. They pass a naive hash comparison (and did pass the existing validators, `twine check`, and `check-wheel-contents`), but PyPI's stricter parser rejects them as "file contents do not match RECORD". `repair_wheel.py` now strips directory entries while repacking so wheels contain only files, and both `repair_wheel.py` and `check_wheel_record.py` now hard-fail on any directory entry in the ZIP or RECORD -- closing the validation gap that let this reach PyPI. (The directory entries originate from `scikit-build-core`; the repair-layer strip makes the output canonical regardless of build-backend version. Already-uploaded files can remain as-is per PyPI; the fix applies to future uploads.)
+
 - **Windows access violation on teardown, regressed by the ChucK update** (`thirdparty/chuck/core/chuck.cpp`, `scripts/update.sh`, `scripts/patches/`): The ChucK core update overwrote vendored source and dropped the numchuck local patch that adds a 50ms post-stop delay in `ChucK::shutdown()` for Windows (WASAPI/DirectSound threads need time to terminate before memory is freed; see `docs/windows_fix.md`). Without it, CI crashed with `0xC0000005` (exit 3221225477) during garbage-collection of `Chuck` instances between tests. Restored the delay, and added `scripts/patches/0001-windows-shutdown-delay.patch` plus an `apply_chuck_patches` step in `update.sh` that re-applies local chuck patches after every update and hard-fails if one no longer applies -- so this cannot silently regress again.
 
 - **Build break after ChucK core update: `ChucK::shutdown()` is now protected** (`src/_numchuck.cpp`): The update reverted numchuck's local patch that had made `shutdown()` public (upstream keeps it protected; it is invoked by `~ChucK()`). Rather than re-patch the header, the binding's `shutdown` method no longer calls it directly and instead only clears the Python-side chout/cherr and instance callbacks. VM teardown happens when the high-level `Chuck.close()` drops its sole reference to the instance, triggering the destructor -- preserving the prior teardown order (callbacks cleared before VM shutdown), and the restored 50ms delay still runs via the destructor on both the explicit-close and garbage-collection paths.

{numchuck-0.2.0 → numchuck-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: numchuck
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python bindings for ChucK audio programming language
 Keywords: chuck,audio,music,synthesis,live-coding
 Author-Email: Shakeeb Alireza <shakfu@users.noreply.github.com>

{numchuck-0.2.0 → numchuck-0.2.1}/TODO.md

@@ -9,6 +9,43 @@
 
 ---
 
+## Real-time Audio: Global UGen Taps
+
+### High Priority
+
+- [ ] **Remove the audio-thread allocation in tap capture** (`src/_numchuck.cpp`, `capture_taps`)
+  - ChucK keeps `m_global_ugens` private (`chuck_globals.h:356`) and exposes only
+    `getGlobalUGenSamples(const char *, ...)`, so every capture builds a `std::string`
+    temporary for the map lookup -- heap-free only when the small-string optimization
+    covers the name
+  - Bounded in count (one lookup per active tap per block, taps capped at 8) and
+    chuck-max's perform routine does the same, but it is still a potentially
+    unbounded-latency call on the audio thread
+  - Fix: vendored patch under `scripts/patches/` exposing a UGen accessor, resolve the
+    `Chuck_UGen *` once in `add_tap()`, then read the buffer directly per block.
+    `apply_patches()` in `scripts/update.sh` re-applies it after a chuck update
+
+- [ ] **Run the tap tearing regression test in CI**
+  (`tests/test_ugen_tap.py::test_realtime_tap_reads_are_never_torn`)
+  - The test is marked `realtime`; every CI job filters with `-k "not realtime"`
+    (`.github/workflows/ci.yml:71`, `wheels.yml:72`, `pip-test.yml:47`), so the check
+    that catches spliced tap reads never runs there
+  - It is the only guard against a regression that was silent in normal use: 0.3% of
+    full-ring reads, correct-looking data with a discontinuity in the middle
+  - Options: a dummy/virtual audio device on the CI runners, or a harness that drives
+    the capture path from a worker thread without real hardware
+
+### Notes
+
+- [x] **Seqlock reader must back off, not spin** (`src/_numchuck.cpp`, `read_tap_snapshot`)
+  - The first version retried 256 times with no delay and timed out spuriously: the
+    collision check is so cheap that all attempts fit inside the single publish window
+    they were waiting on
+  - Now waits 200 us between attempts, with the GIL released, over 64 attempts.
+    Worth remembering for any future lock-free reader in this codebase
+
+---
+
 ## REPL Issues
 
 ### High Priority

{numchuck-0.2.0 → numchuck-0.2.1}/docs/api/api/chuck.rst

@@ -32,6 +32,28 @@ ChucK Class
    .. automethod:: get_global_float
    .. automethod:: get_global_string
 
+   .. rubric:: Global Arrays
+
+   .. automethod:: set_global_int_array
+   .. automethod:: set_global_float_array
+   .. automethod:: set_global_int_array_value
+   .. automethod:: set_global_float_array_value
+   .. automethod:: set_global_associative_int_array_value
+   .. automethod:: set_global_associative_float_array_value
+   .. automethod:: get_global_int_array
+   .. automethod:: get_global_float_array
+   .. automethod:: get_global_int_array_value
+   .. automethod:: get_global_float_array_value
+   .. automethod:: get_global_associative_int_array_value
+   .. automethod:: get_global_associative_float_array_value
+
+   .. rubric:: Global UGens
+
+   .. automethod:: get_ugen_samples
+   .. automethod:: add_tap
+   .. automethod:: remove_tap
+   .. automethod:: list_taps
+
    .. rubric:: Global Events
 
    .. automethod:: signal_global_event
@@ -45,12 +67,21 @@ ChucK Class
    .. automethod:: remove_all_shreds
    .. automethod:: replace_shred
    .. automethod:: get_all_shred_ids
+   .. automethod:: get_ready_shred_ids
+   .. automethod:: get_blocked_shred_ids
+   .. automethod:: get_last_shred_id
+   .. automethod:: get_next_shred_id
    .. automethod:: get_shred_info
+   .. automethod:: abort_current_shred
+   .. automethod:: subscribe_shred_watcher
+   .. automethod:: remove_shred_watcher
 
    .. rubric:: VM Control
 
    .. automethod:: clear_vm
    .. automethod:: reset_shred_id
+   .. automethod:: set_adaptive
+   .. automethod:: get_adaptive
 
    .. rubric:: Status Methods
 

{numchuck-0.2.0 → numchuck-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "numchuck"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python bindings for ChucK audio programming language"
 readme = "README.md"
 requires-python = ">=3.10"

{numchuck-0.2.0 → numchuck-0.2.1}/scripts/check_wheel_record.py

@@ -6,6 +6,9 @@ Checks that:
   2. Every file in RECORD exists in the ZIP (no dangling entries)
   3. SHA256 hashes match for all recorded files
   4. File sizes match for all recorded files
+  5. No directory entries (names ending in "/") appear in the ZIP or RECORD --
+     these carry the empty-content hash and pass a naive hash check, but PyPI's
+     strict parser rejects them as "file contents do not match RECORD"
 
 See: https://blog.pypi.org/posts/2025-08-07-wheel-archive-confusion-attacks/
 
@@ -63,6 +66,15 @@ def validate_wheel(path: str) -> list[str]:
         actual_files = {n for n in zf.namelist() if n != record_name}
         recorded_files = set(recorded.keys())
 
+        # Reject directory entries (names ending in "/"). Canonical wheels
+        # contain only files. A directory entry carries the empty-content hash
+        # in RECORD, so it slips past the hash/size checks below, but PyPI's
+        # strict parser rejects it as "file contents do not match RECORD".
+        for name in sorted(n for n in actual_files if n.endswith("/")):
+            errors.append(f"directory entry in ZIP (not allowed): {name}")
+        for name in sorted(n for n in recorded_files if n.endswith("/")):
+            errors.append(f"directory entry in RECORD (not allowed): {name}")
+
         # Check for files in ZIP but not in RECORD (smuggled files)
         extra = sorted(actual_files - recorded_files)
         for name in extra:

{numchuck-0.2.0 → numchuck-0.2.1}/scripts/repair_wheel.py

@@ -151,6 +151,13 @@ def _validate_record(wheel_path: str) -> None:
         actual_files = {n for n in zf.namelist() if n != record_name}
         recorded_files = set(recorded.keys())
 
+        # Directory entries (names ending in "/") are not allowed -- they carry
+        # the empty-content hash and pass the hash check below, but PyPI's
+        # strict parser rejects them. The rewrite above strips them; this is the
+        # backstop.
+        for name in sorted(n for n in actual_files | recorded_files if n.endswith("/")):
+            errors.append(f"directory entry not allowed: {name}")
+
         for name in sorted(actual_files - recorded_files):
             errors.append(f"file in ZIP but not in RECORD: {name}")
         for name in sorted(recorded_files - actual_files):
@@ -192,6 +199,13 @@ def rename_in_wheel(
     with ZipFile(src_wheel, "r") as zin, ZipFile(dst_wheel, "w", ZIP_DEFLATED) as zout:
         record_path = _record_path(zin)
         for item in zin.infolist():
+            # Drop directory entries (names ending in "/"). Canonical wheels
+            # contain only files; a directory entry listed in RECORD (with the
+            # empty-content hash) passes a naive hash comparison but trips
+            # PyPI's strict RECORD/archive check -> "file contents do not match
+            # RECORD". See check_wheel_record.py for the validation gate.
+            if item.filename.endswith("/"):
+                continue
             data = zin.read(item.filename)
             stem = Path(item.filename).stem
             should_rename = (

numchuck-0.2.1/scripts/update.sh

@@ -0,0 +1,466 @@
+#!/usr/bin/env bash
+#
+# update.sh
+#
+# Refresh the vendored upstream trees.
+#
+#   thirdparty/chuck/{core,host}  <-  ccrma/chuck        <chuck>/src/{core,host}
+#   examples/                     <-  ccrma/chuck        <chuck>/examples
+#   thirdparty/chugins/           <-  ccrma/chugins
+#
+# Every one of these trees carries numchuck-local content that upstream knows
+# nothing about: the CMakeLists.txt files, the pre-generated bison/flex output
+# committed for the Windows build, the python/ and test/ example sets, the
+# built chugins under examples/chugins, and the chugins that do not come from
+# ccrma/chugins at all (AbletonLink, AudioUnit, CLAP, Fauck, PdPatch, VST3).
+#
+# So each tree is rebuilt as: upstream, minus the entries listed as superseded
+# or as build cruft, plus every path that exists locally but not upstream.
+# Nothing has to be enumerated for a local file to survive an update.
+#
+# The consequence: a local *edit* to a file upstream also owns is lost on
+# update. Keep those as patches under scripts/patches/ (chuck) and
+# scripts/patches/chugins/ so they are re-applied after every update --
+# docs/windows_fix.md documents a regression caused by exactly this. For the
+# same reason the script refuses to run against a dirty vendored tree.
+
+set -euo pipefail
+shopt -s nullglob dotglob
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${REPO_ROOT}"
+
+CHUCK_REPO=${CHUCK_REPO:-https://github.com/ccrma/chuck.git}
+CHUGINS_REPO=${CHUGINS_REPO:-https://github.com/ccrma/chugins.git}
+
+BUILD_DIR=build
+THIRDPARTY_DIR=thirdparty
+CHUCK_SRC=${BUILD_DIR}/chuck-src
+CHUGINS_SRC=${BUILD_DIR}/chugins-src
+CHUCK_DIR=${THIRDPARTY_DIR}/chuck
+CHUGINS_DIR=${THIRDPARTY_DIR}/chugins
+EXAMPLES_DIR=examples
+PATCH_DIR=scripts/patches
+CHUGINS_PATCH_DIR=${PATCH_DIR}/chugins
+
+# upstream example entries superseded by the numchuck overlay: hanoi/, otf/ and
+# util/ hold the maintained copies, README.md replaces README, book/ is a large
+# set of tutorial sources not shipped here.
+PRUNE_EXAMPLES=(
+	README
+	book
+	hanoi.ck
+	hanoi++.ck
+	hanoi2.ck
+	hanoi3.ck
+	help.ck
+	otf_01.ck
+	otf_02.ck
+	otf_03.ck
+	otf_04.ck
+	otf_05.ck
+	otf_06.ck
+	otf_07.ck
+	status.ck
+)
+
+# upstream chugins entries not carried: the makefile/Visual Studio/debian build
+# systems this project replaces with CMake, and Faust/ (superseded by the
+# locally vendored Fauck/).
+PRUNE_CHUGINS=(
+	.github
+	.gitattributes
+	.gitmodules
+	.travis.yml
+	chugins.dsw
+	chugins.sln
+	debian
+	Faust
+	makefile
+)
+
+# per-chugin build cruft, pruned wherever it appears in the upstream tree
+PRUNE_CHUGINS_GLOBS=(
+	'makefile'
+	'makefile.*'
+	'Makefile'
+	'*.dsp'
+	'*.dsw'
+	'*.sln'
+	'*.vcxproj'
+	'*.vcxproj.*'
+	'*.xcodeproj'
+	'.gitignore'
+	'*.o'
+	'*.obj'
+	'*.chug'
+	'*.a'
+	'*.so'
+	'*.dylib'
+)
+
+CHUCK_REF=""
+CHUGINS_REF=""
+DO_CHUCK=0
+DO_EXAMPLES=0
+DO_CHUGINS=0
+KEEP_OLD=0
+FORCE=0
+
+
+function info() {
+	echo "==> $*"
+}
+
+function warn() {
+	echo "warning: $*" >&2
+}
+
+function die() {
+	echo "ERROR: $*" >&2
+	exit 1
+}
+
+function usage() {
+	cat <<-'EOF'
+	usage: scripts/update.sh [options] [target ...]
+
+	Refresh the vendored upstream trees, carrying forward every path that
+	exists locally but not upstream.
+
+	targets:
+	  chuck       thirdparty/chuck from ccrma/chuck, then re-apply patches
+	  examples    examples/ from ccrma/chuck
+	  chugins     thirdparty/chugins from ccrma/chugins
+	  all         all of the above (the default)
+
+	options:
+	  --ref REF           chuck branch or tag to clone (default: upstream HEAD)
+	  --chugins-ref REF   chugins branch or tag to clone
+	  --keep-old          keep the replaced trees under build/ for inspection
+	  --force             update even if a vendored tree has uncommitted changes
+	  -h, --help          show this message
+	EOF
+}
+
+function parse_args() {
+	local target selected=0
+
+	while [ $# -gt 0 ]; do
+		case "$1" in
+			--keep-old)   KEEP_OLD=1 ;;
+			--force)      FORCE=1 ;;
+			--ref)        shift; [ $# -gt 0 ] || die "--ref needs a value"; CHUCK_REF="$1" ;;
+			--chugins-ref) shift; [ $# -gt 0 ] || die "--chugins-ref needs a value"; CHUGINS_REF="$1" ;;
+			-h|--help)    usage; exit 0 ;;
+			-*)           die "unknown option: $1 (try --help)" ;;
+			*)
+				target="$1"
+				selected=1
+				case "${target}" in
+					chuck)    DO_CHUCK=1 ;;
+					examples) DO_EXAMPLES=1 ;;
+					chugins)  DO_CHUGINS=1 ;;
+					all)      DO_CHUCK=1; DO_EXAMPLES=1; DO_CHUGINS=1 ;;
+					*)        die "unknown target: ${target} (try --help)" ;;
+				esac
+				;;
+		esac
+		shift
+	done
+
+	if [ "${selected}" -eq 0 ]; then
+		DO_CHUCK=1
+		DO_EXAMPLES=1
+		DO_CHUGINS=1
+	fi
+}
+
+# Report the CHUCK_VERSION_STRING recorded in a chuck_def.h.
+function chuck_version() {
+	local header="$1"
+	if [ ! -f "${header}" ]; then
+		echo "unknown"
+		return 0
+	fi
+	sed -n 's/^#define[[:space:]]*CHUCK_VERSION_STRING[[:space:]]*"\(.*\)".*/\1/p' "${header}" | head -1
+}
+
+# Refuse to clobber uncommitted edits to files upstream also owns; untracked
+# additions are safe because the overlay pass carries them forward.
+function assert_not_dirty() {
+	local path="$1" dirty
+	[ "${FORCE}" -eq 0 ] || return 0
+	[ -d .git ] || return 0
+	dirty="$(git status --porcelain -- "${path}" | grep -v '^??' || true)"
+	[ -n "${dirty}" ] || return 0
+
+	echo "ERROR: ${path} has uncommitted changes to upstream-owned files:" >&2
+	echo "${dirty}" >&2
+	echo >&2
+	echo "       An update overwrites them. Commit them, or capture them as a" >&2
+	echo "       patch under ${PATCH_DIR}/ so they are re-applied after every" >&2
+	echo "       update (see docs/windows_fix.md). Use --force to override." >&2
+	exit 1
+}
+
+# Copy every entry under <src-root> that has no counterpart under
+# <upstream-root> into <dst-root>, recursing into directories the two trees
+# share. This is what preserves the numchuck-local content of a vendored tree
+# without having to enumerate it.
+OVERLAY_KEPT=()
+
+function overlay_local_only() {
+	local src_root="$1" up_root="$2" dst_root="$3" rel="${4:-}"
+	local dir="${src_root}${rel:+/$rel}"
+	local entry name child
+
+	[ -d "${dir}" ] || return 0
+
+	for entry in "${dir}"/*; do
+		name="${entry##*/}"
+		child="${rel:+${rel}/}${name}"
+		if [ ! -e "${up_root}/${child}" ] && [ ! -L "${up_root}/${child}" ]; then
+			mkdir -p "${dst_root}${rel:+/$rel}"
+			cp -Rp "${entry}" "${dst_root}/${child}"
+			OVERLAY_KEPT+=("${child}")
+		elif [ -d "${entry}" ] && [ ! -L "${entry}" ]; then
+			overlay_local_only "${src_root}" "${up_root}" "${dst_root}" "${child}"
+		fi
+	done
+}
+
+function report_kept() {
+	local label="$1" entry
+	if [ ${#OVERLAY_KEPT[@]} -eq 0 ]; then
+		warn "no local-only paths found under ${label} -- expected at least a CMakeLists.txt"
+		return 0
+	fi
+	info "preserved ${#OVERLAY_KEPT[@]} local-only path(s) in ${label}:"
+	for entry in "${OVERLAY_KEPT[@]}"; do
+		echo "    ${entry}"
+	done
+}
+
+# Copy the numchuck build files back over the staged tree. The overlay already
+# preserves the ones upstream does not ship; this covers the ones it does
+# (chugins/WarpBuf) and guards against upstream adding more of them later.
+function restore_cmakelists() {
+	local src_root="$1" dst_root="$2" rel
+
+	while IFS= read -r rel; do
+		rel="${rel#"${src_root}"/}"
+		mkdir -p "${dst_root}/$(dirname "${rel}")"
+		cp -p "${src_root}/${rel}" "${dst_root}/${rel}"
+	done < <(find "${src_root}" -name CMakeLists.txt)
+}
+
+# Replace <target> with <staged>, parking the old tree under build/.
+function swap_in() {
+	local target="$1" staged="$2" backup
+	backup="${BUILD_DIR}/$(basename "${target}")-old"
+
+	rm -rf "${backup}"
+	if [ -e "${target}" ]; then
+		mv "${target}" "${backup}"
+	fi
+	mv "${staged}" "${target}"
+
+	if [ "${KEEP_OLD}" -eq 1 ]; then
+		info "previous tree kept at ${backup}"
+	else
+		rm -rf "${backup}"
+	fi
+}
+
+# clone_repo <url> <dest> <ref>
+function clone_repo() {
+	local url="$1" dest="$2" ref="$3"
+	local args=(--depth=1)
+
+	if [ -n "${ref}" ]; then
+		args+=(--branch "${ref}")
+	fi
+
+	info "cloning ${url}${ref:+ @ ${ref}}"
+	mkdir -p "${BUILD_DIR}"
+	rm -rf "${dest}"
+	git clone "${args[@]}" "${url}" "${dest}" >/dev/null 2>&1 || die "clone failed: ${url}"
+
+	info "upstream $(basename "${dest}") at $(git -C "${dest}" rev-parse --short HEAD)"
+	rm -rf "${dest}/.git"
+}
+
+# Re-apply numchuck local patches to a freshly updated vendored tree. A
+# wholesale update overwrites it, silently dropping any source patch (e.g. the
+# Windows shutdown delay -- see docs/windows_fix.md, which regressed exactly
+# this way). Hard-fail if a patch no longer applies so the conflict is noticed
+# instead of shipping a broken build.
+function apply_patches() {
+	local dir="$1" required="${2:-0}" patch applied=0
+
+	for patch in "${dir}"/*.patch; do
+		info "applying patch: ${patch}"
+		if ! git apply "${patch}"; then
+			echo "ERROR: failed to apply ${patch}" >&2
+			echo "       upstream source likely changed; resolve manually." >&2
+			return 1
+		fi
+		applied=$((applied + 1))
+	done
+
+	if [ "${applied}" -eq 0 ] && [ "${required}" -eq 1 ]; then
+		warn "no patches found in ${dir}/"
+	fi
+}
+
+function update_chuck() {
+	local staged="${BUILD_DIR}/chuck-new"
+
+	[ -d "${CHUCK_SRC}/src/core" ] || die "no src/core in ${CHUCK_SRC}"
+
+	info "vendored chuck $(chuck_version "${CHUCK_DIR}/core/chuck_def.h") -> \
+$(chuck_version "${CHUCK_SRC}/src/core/chuck_def.h")"
+
+	rm -rf "${staged}"
+	mkdir -p "${staged}"
+	cp -Rp "${CHUCK_SRC}/src/core" "${staged}/core"
+	cp -Rp "${CHUCK_SRC}/src/host" "${staged}/host"
+
+	# CMakeLists.txt, the committed bison/flex output, anything else local
+	OVERLAY_KEPT=()
+	overlay_local_only "${CHUCK_DIR}" "${CHUCK_SRC}/src" "${staged}"
+	report_kept "${CHUCK_DIR}"
+	restore_cmakelists "${CHUCK_DIR}" "${staged}"
+
+	swap_in "${CHUCK_DIR}" "${staged}"
+	apply_patches "${PATCH_DIR}" 1
+}
+
+function update_examples() {
+	local upstream="${CHUCK_SRC}/examples"
+	local staged="${BUILD_DIR}/examples-new"
+	local entry before after
+
+	[ -d "${upstream}" ] || die "no examples in ${CHUCK_SRC}"
+
+	before=$(find "${EXAMPLES_DIR}" -type f 2>/dev/null | wc -l | tr -d ' ' || true)
+
+	rm -rf "${staged}"
+	cp -Rp "${upstream}" "${staged}"
+
+	for entry in "${PRUNE_EXAMPLES[@]}"; do
+		rm -rf "${staged:?}/${entry}"
+	done
+
+	# python/, max/, test/, the built chugins, data/amen.wav, midi/data, ...
+	OVERLAY_KEPT=()
+	overlay_local_only "${EXAMPLES_DIR}" "${upstream}" "${staged}"
+	report_kept "${EXAMPLES_DIR}"
+
+	# entries upstream added since the last update, worth a look
+	for entry in "${staged}"/*; do
+		[ -e "${EXAMPLES_DIR}/${entry##*/}" ] || info "new from upstream: ${entry##*/}"
+	done
+
+	swap_in "${EXAMPLES_DIR}" "${staged}"
+
+	after=$(find "${EXAMPLES_DIR}" -type f | wc -l | tr -d ' ')
+	info "examples: ${before} -> ${after} files"
+}
+
+function update_chugins() {
+	local staged="${BUILD_DIR}/chugins-new"
+	local entry glob
+
+	[ -d "${CHUGINS_SRC}" ] || die "no chugins clone at ${CHUGINS_SRC}"
+	[ -f "${CHUGINS_DIR}/CMakeLists.txt" ] || die "missing ${CHUGINS_DIR}/CMakeLists.txt"
+
+	rm -rf "${staged}"
+	cp -Rp "${CHUGINS_SRC}" "${staged}"
+
+	for entry in "${PRUNE_CHUGINS[@]}"; do
+		rm -rf "${staged:?}/${entry}"
+	done
+
+	# Prune before the overlay so that local files sharing these names (the
+	# AudioUnit and Fauck makefiles, for instance) are restored afterwards.
+	# chuck/ is the chugin SDK and chuginate/ is a project template: their
+	# makefiles are payload, not this project's build system.
+	for glob in "${PRUNE_CHUGINS_GLOBS[@]}"; do
+		find "${staged}" \
+			-path "${staged}/chuck" -prune -o \
+			-path "${staged}/chuginate" -prune -o \
+			-name "${glob}" -prune -exec rm -rf {} +
+	done
+
+	# AbletonLink/, AudioUnit/, CLAP/, Fauck/, PdPatch/, VST3/, every
+	# per-chugin CMakeLists.txt, the local Sigmund and WarpBuf bits, ...
+	OVERLAY_KEPT=()
+	overlay_local_only "${CHUGINS_DIR}" "${CHUGINS_SRC}" "${staged}"
+	report_kept "${CHUGINS_DIR}"
+	restore_cmakelists "${CHUGINS_DIR}" "${staged}"
+
+	# upstream tracks rubberband/libsndfile/libsamplerate under WarpBuf as
+	# submodules; a plain clone leaves those as empty directories
+	find "${staged}" -type d -empty -delete
+
+	# sigmund.c duplicates symbols in sigmund-dsp.c, so it is kept out of the
+	# build under a .orig suffix rather than dropped -- renaming the upstream
+	# copy keeps it tracking upstream.
+	if [ -f "${staged}/Sigmund/sigmund.c" ]; then
+		mv -f "${staged}/Sigmund/sigmund.c" "${staged}/Sigmund/sigmund.c.orig"
+	fi
+
+	for entry in "${staged}"/*; do
+		[ -e "${CHUGINS_DIR}/${entry##*/}" ] || info "new from upstream: ${entry##*/}"
+	done
+
+	# a chugin upstream added is not built until it is added to CMakeLists.txt
+	for entry in "${staged}"/*/; do
+		entry="$(basename "${entry}")"
+		case "${entry}" in
+			chuck|chuginate|notes) continue ;;
+		esac
+		if ! grep -q "add_subdirectory(${entry})" "${CHUGINS_DIR}/CMakeLists.txt"; then
+			warn "${entry} is not in ${CHUGINS_DIR}/CMakeLists.txt -- not built"
+		fi
+	done
+
+	swap_in "${CHUGINS_DIR}" "${staged}"
+	apply_patches "${CHUGINS_PATCH_DIR}"
+}
+
+function main() {
+	parse_args "$@"
+
+	if [ "${DO_CHUCK}" -eq 1 ]; then
+		assert_not_dirty "${CHUCK_DIR}"
+	fi
+	if [ "${DO_CHUGINS}" -eq 1 ]; then
+		assert_not_dirty "${CHUGINS_DIR}"
+	fi
+
+	if [ "${DO_CHUCK}" -eq 1 ] || [ "${DO_EXAMPLES}" -eq 1 ]; then
+		clone_repo "${CHUCK_REPO}" "${CHUCK_SRC}" "${CHUCK_REF}"
+	fi
+	if [ "${DO_CHUGINS}" -eq 1 ]; then
+		clone_repo "${CHUGINS_REPO}" "${CHUGINS_SRC}" "${CHUGINS_REF}"
+	fi
+
+	if [ "${DO_CHUCK}" -eq 1 ]; then
+		update_chuck
+	fi
+	if [ "${DO_EXAMPLES}" -eq 1 ]; then
+		update_examples
+	fi
+	if [ "${DO_CHUGINS}" -eq 1 ]; then
+		update_chugins
+	fi
+
+	rm -rf "${CHUCK_SRC}" "${CHUGINS_SRC}"
+
+	info "done -- review with 'git status' and rebuild with 'make build'"
+}
+
+main "$@"