Skip to content

Commit bb9485d

Browse files
authored
Merge pull request #35 from tap/ccr-34c45a78-kfxhky
Audit of 0.10.0, and Phase 8: its findings closed (8.1–8.7)
2 parents 41c1ae0 + 413c0f2 commit bb9485d

33 files changed

Lines changed: 3691 additions & 805 deletions

‎.github/workflows/style.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ name: Tap House Style
1414
on: [push, pull_request]
1515

1616
# Least privilege: the jobs only read the repository. Third-party actions are pinned by
17-
# commit SHA (the tag each SHA was cut from is noted beside it).
17+
# commit SHA (the tag each SHA was cut from is noted beside it). The one reference by tag is the
18+
# family's own drift check (tap/taphouse, below): its `ref` input must name the same release of
19+
# the canonical files, and the family moves that tag together, so it is pinned by release, not SHA.
1820
permissions:
1921
contents: read
2022

‎CHANGELOG.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,80 @@ Changes to the Python class contract and to the object's behavior, newest first.
44
breaking changes to the contract are allowed where they buy correctness (D5 in
55
`docs/PRODUCTION-PLAN.md`); each is recorded here.
66

7+
## Unreleased
8+
9+
### Changed — type hints map as a reader expects
10+
11+
- **`Annotated[X, …]` and `Final[X]` fields are `X`; a union of several kinds passes the atom as
12+
it is; numpy scalar types map to the kinds they hold; `Optional[tuple[…]]` names its outputs.**
13+
A `float | int` field used to become a symbol attribute that stored `""` for any number; now it
14+
takes the value as the atom carried it (an `int`, `float` or `str`), as an unannotated parameter
15+
does. `Annotated` and `Final` used to be symbols; `np.float64` and friends too; and
16+
`-> tuple[float, float] | None` bound one output and then reported every sample as not a number.
17+
The same holds for hints read as written. (Plan 8.6, audit A8.)
18+
19+
### Changed — helper modules follow the class file
20+
21+
- **A helper module in `python/` is imported afresh when a class file that changed is saved.**
22+
Before each execution of a class file the loader drops from `sys.modules` every source module
23+
imported from the folder (not the class modules themselves, nor compiled extensions), so the
24+
fresh class imports the helper's current source; and the interpreter writes no bytecode, so the
25+
stale-`.pyc` hazard fixed for class files in 0.9.0 cannot return for helpers. A save of the
26+
helper alone is still not watched. Helpers used to load once per Max session. (Plan 8.5, audit
27+
A7.)
28+
29+
### Changed — nothing of yours posts from the audio thread
30+
31+
- **What `process()` prints, or warns, is posted from Max's main thread.** A `print()` or a numpy
32+
`RuntimeWarning` in `process()` used to post to the console from the audio thread (or the worker
33+
thread), taking a lock on the way. Now a complete line printed on any thread but Max's main one
34+
is queued, lock-free and without allocating, and posted from the main thread a moment later;
35+
lines are assembled per thread, so two threads printing pieces of a line no longer mix them. A
36+
flood is coalesced: 256 lines queue, the rest are dropped and counted in one line. Lines printed
37+
on the main thread post at once, as before. (Plan 8.4, audit A5.)
38+
39+
### Changed — worker mode never waits forever
40+
41+
- **A `process()` that does not return when the worker stops is interrupted, then abandoned.**
42+
Stopping the worker — DSP off, a chain rebuild, the object deleted — waits up to 100 ms, then
43+
raises `WorkerStopped` (a `BaseException`) into the thread: a pure-Python loop ends, that vector
44+
is silence, the console says so once per load, and the class's audio stays bound. If it still has
45+
not returned 250 ms later it is blocked in a call Python cannot interrupt, and the thread is
46+
abandoned: audio continues on a new worker, the console says the thread keeps costing a core
47+
until Max quits, and the object keeps its Python state alive for it. Before, stopping the worker
48+
waited for `process()` to return, so such a class froze Max when DSP toggled or the patch closed.
49+
The worker thread also runs on a 16 MiB stack, what CPython gives its own threads on macOS, where
50+
the default 512 KiB was too little for Python that recurses through a C boundary. (Plan 8.3,
51+
audit A1 and A6.)
52+
53+
### Changed — more names are reserved
54+
55+
- **A method or field named like a message Max sends with C arguments is not exposed**, with the
56+
console saying so: `dspstate`, `fileusage`, `patchlineupdate`, `inputchanged`,
57+
`multichanneloutputs`, `edclose`, `okclose`, `oksize`, `paint`, `dictionary`, `getplaystate`,
58+
`key`, the mouse and focus messages, `mousewheel`, and the `*_setup` names — every message min
59+
treats as `A_CANT`, plus Max's own — and, as a guard, any name the Max object already answers
60+
itself. A Python method of such a name used to be registered as an ordinary message, which Max
61+
then called with a `long` or a pointer: the crash that every save once caused through
62+
`filechanged`, in its general form. (Plan 8.2, audit A3.)
63+
64+
### Fixed
65+
66+
- **Windows: a package under a folder with a non-ASCII name is watched.** The path handed to Max's
67+
file watcher, and the paths in the console's "No file" and "Failed to load" lines, were converted
68+
with the ANSI code page on Windows, where Max expects UTF-8; for a user whose `Documents` folder
69+
has an accented character the watcher failed and hot reload was silently off. Every path shown
70+
to Max or the console is UTF-8 now. (Plan 8.7, audit A9.)
71+
- **Samples computed before `process()` raised are sanitized.** A `process()` that returned NaN for
72+
part of a vector and then raised let those NaNs through; the contract says non-finite output is
73+
replaced with 0.0, and now it is on that path too. (Plan 8.2, audit A2.)
74+
- **The documents say what the guards cover.** No Python exception, `sys.exit()` included, takes
75+
Max down; what never reaches Python's exception machinery — `os._exit()`, a crash in a C
76+
extension, code that never returns — is not caught, and the ReadMe now says so, as it says that
77+
helper modules load once per Max session and that a second embedded CPython in the same Max is
78+
unsupported. `assemble-package.py --merge` refuses a zip whose entries or symlinks would land
79+
outside the package. (Plan 8.1.)
80+
781
## 0.10.0 — 2026-10-01
882

983
### Added — one package for every platform

‎CLAUDE.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,11 @@ attaches all the zips + SHA256s to a release — a pre-release for 0.x, a draft
145145

146146
- **Honest limits are pinned, not hidden.** A known bug or limit gets a test that states it (named
147147
for the promise, with the plan item that will change it); fixes land against a test that reproduces
148-
the bug first. The core battery is where that happens.
148+
the bug first. The core battery is where that happens. Limits no test can pin are written in the
149+
ReadMe's errors paragraph and stay there: the guards catch every Python *exception*, not a
150+
process exit below Python (`os._exit()`), a crash in a C extension, or code that never returns;
151+
helper modules load once per session; a second embedded CPython in the same Max is unsupported.
152+
Never let a document claim more than that.
149153
- **Style:** `STYLE.md`, `.clang-format`, `.clang-tidy`, `.pre-commit-config.yaml`, `scripts/tidy.sh`
150154
and the SessionStart hook are canonical TapHouse copies — never hand-edit them (CI drift-checks).
151155
New files use the STYLE.md §3 SPDX banner. clang-tidy compiles with a clang front end; treat it as a

0 commit comments

Comments
 (0)