@zeeuw/riff 0.0.0-stage → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +46 -2
  3. package/data/registry-data.js +3 -0
  4. package/data/signatures.js +3 -0
  5. package/docs/clean-room.md +450 -0
  6. package/package.json +69 -4
  7. package/src/audio/clock.js +383 -0
  8. package/src/audio/engine.js +678 -0
  9. package/src/audio/index.js +394 -0
  10. package/src/audio/offline.js +73 -0
  11. package/src/audio/params.js +397 -0
  12. package/src/audio/samples.js +274 -0
  13. package/src/audio/unlock.js +70 -0
  14. package/src/audio/voices.js +44 -0
  15. package/src/combinators.js +150 -0
  16. package/src/compat.js +16 -0
  17. package/src/constructors.js +236 -0
  18. package/src/controls.js +199 -0
  19. package/src/draw.js +252 -0
  20. package/src/euclid.js +57 -0
  21. package/src/evaluate.js +251 -0
  22. package/src/extras/check.js +678 -0
  23. package/src/extras/describe.js +433 -0
  24. package/src/extras/editor.js +369 -0
  25. package/src/extras/index.js +10 -0
  26. package/src/fraction.js +300 -0
  27. package/src/hap.js +64 -0
  28. package/src/helpers.js +68 -0
  29. package/src/index.js +74 -0
  30. package/src/mini/index.js +36 -0
  31. package/src/mini/parser.js +400 -0
  32. package/src/ops.js +293 -0
  33. package/src/outline.js +175 -0
  34. package/src/pattern.js +365 -0
  35. package/src/random.js +344 -0
  36. package/src/register.js +83 -0
  37. package/src/registry.js +52 -0
  38. package/src/samples.js +14 -0
  39. package/src/sampling.js +123 -0
  40. package/src/scope.js +77 -0
  41. package/src/signals.js +76 -0
  42. package/src/stepwise.js +150 -0
  43. package/src/structure.js +636 -0
  44. package/src/time.js +70 -0
  45. package/src/tonal.js +583 -0
  46. package/src/transforms.js +125 -0
  47. package/src/transpile.js +394 -0
  48. package/src/util.js +80 -0
  49. package/src/visuals.js +216 -0
@@ -0,0 +1,3 @@
1
+ // Generated by tools/registry/build.mjs (npm run registry); do not edit.
2
+ // check()'s argument signatures: name -> [methodTypes, methodMax, freeTypes, freeMax].
3
+ export default {"accelerate":[null,1,null,1],"activeLabel":[null,1,null,1],"ad":[null,1,null,null],"add":[null,1,null,null],"addVoicings":[null,null,null,3],"adsr":[null,1,null,2],"amp":[null,1,null,1],"analyze":[null,1,null,1],"anchor":[null,1,null,1],"ar":[null,1,null,null],"arp":[null,1,null,null],"arpWith":[null,1,null,null],"arrange":[null,null,null,null],"asNumber":[null,0,null,null],"att":[["n"],1,["n"],1],"attack":[["n"],1,["n"],1],"bandf":[null,1,null,1],"bp":[null,1,null,1],"bpf":[null,1,null,1],"bandq":[null,1,null,1],"bpq":[null,1,null,1],"bank":[["s"],1,["s"],1],"bbexpr":[null,1,null,1],"byteBeatExpression":[null,1,null,1],"bbst":[null,1,null,1],"byteBeatStartTime":[null,1,null,1],"begin":[null,1,null,1],"binary":[null,null,null,1],"binaryN":[null,null,null,2],"binshift":[null,1,null,1],"bite":[null,2,null,3],"bpa":[null,1,null,1],"bpattack":[null,1,null,1],"bpd":[null,1,null,1],"bpdecay":[null,1,null,1],"bpe":[null,1,null,1],"bpenv":[null,1,null,1],"bpr":[null,1,null,1],"bprelease":[null,1,null,1],"bps":[null,1,null,1],"bpsustain":[null,1,null,1],"brak":[null,0,null,1],"ccn":[null,1,null,1],"ccv":[null,1,null,1],"ch":[null,1,null,1],"channels":[null,1,null,1],"channel":[null,1,null,1],"choose":[null,null,null,null],"chooseOut":[null,null,null,null],"chooseCycles":[null,null,null,null],"randcat":[null,null,null,null],"chooseCyclesWith":[null,null,null,null],"chooseIn":[null,null,null,null],"chooseInWith":[null,null,null,2],"chop":[null,1,null,2],"chord":[null,1,null,1],"chorus":[null,1,null,1],"chunk":[null,2,null,null],"chunkBack":[null,2,null,null],"chunkBackInto":[null,2,null,null],"chunkInto":[null,2,null,null],"clip":[null,1,null,1],"legato":[null,1,null,1],"coarse":[null,1,null,1],"color":[null,1,null,1],"comb":[null,1,null,1],"compress":[null,2,null,3],"compressor":[null,1,null,1],"compressorAttack":[null,1,null,1],"compressorKnee":[null,1,null,1],"compressorRatio":[null,1,null,1],"compressorRelease":[null,1,null,1],"continuous":[null,null,null,1],"cpm":[null,1,null,null],"cps":[null,1,null,1],"crush":[["n"],1,["n"],1],"ctf":[["n"],1,["n"],1],"cutoff":[["n"],1,["n"],1],"lp":[["n"],1,["n"],1],"lpf":[["n"],1,["n"],1],"ctlNum":[null,1,null,1],"ctranspose":[null,1,null,1],"curve":[null,1,null,1],"cut":[["n"],1,["n"],1],"dec":[["n"],1,["n"],1],"decay":[["n"],1,["n"],1],"degradeBy":[null,1,null,2],"degradeBySeed":[null,2,null,null],"degree":[null,1,null,1],"delay":[["n"],1,["n"],1],"delayfb":[["n"],1,["n"],1],"delayfeedback":[["n"],1,["n"],1],"dfb":[["n"],1,["n"],1],"delayspeed":[null,1,null,1],"delaysync":[null,1,null,1],"delayt":[["n"],1,["n"],1],"delaytime":[["n"],1,["n"],1],"dt":[["n"],1,["n"],1],"deltaSlide":[null,1,null,1],"det":[["n"],1,["n"],1],"detune":[["n"],1,["n"],1],"dict":[["s"],1,["s"],1],"dictionary":[["s"],1,["s"],1],"dist":[["n"],1,["n"],1],"distort":[["n"],1,["n"],1],"distorttype":[null,1,null,1],"distortvol":[null,1,null,1],"djf":[null,1,null,1],"drive":[null,1,null,1],"dry":[null,1,null,1],"ds":[null,1,null,null],"duck":[null,1,null,1],"duckattack":[null,1,null,1],"duckdepth":[null,1,null,1],"duckonset":[null,1,null,1],"dur":[null,1,null,1],"duration":[null,1,null,1],"echo":[null,3,null,null],"echoWith":[null,3,null,null],"end":[null,1,null,1],"enhance":[null,1,null,1],"euclidish":[null,3,null,4],"every":[null,2,null,3],"expression":[null,1,null,1],"fadeInTime":[null,1,null,1],"fadeOutTime":[null,1,null,1],"fadeTime":[null,1,null,1],"fanchor":[null,1,null,1],"fast":[null,1,null,2],"fastChunk":[null,2,null,null],"fastGap":[null,1,null,null],"fft":[null,1,null,1],"firstOf":[null,2,null,null],"fit":[null,0,null,null],"fm":[["n"],1,["n"],1],"fmi":[["n"],1,["n"],1],"fmattack":[null,1,null,1],"fmdecay":[null,1,null,1],"fmenv":[null,1,null,1],"fmh":[["n"],1,["n"],1],"fmrelease":[null,1,null,1],"fmsustain":[null,1,null,1],"fmvelocity":[null,1,null,1],"fmwave":[null,1,null,1],"frameRate":[null,1,null,1],"frames":[null,1,null,1],"freeze":[null,1,null,1],"freq":[null,1,null,1],"fshift":[null,1,null,1],"fshiftnote":[null,1,null,1],"fshiftphase":[null,1,null,1],"ftype":[null,1,null,1],"gain":[["n"],1,["n"],1],"gat":[null,1,null,1],"gate":[null,1,null,1],"getCompat":[null,null,null,0],"getFreq":[null,null,null,1],"harmonic":[null,1,null,1],"hbrick":[null,1,null,1],"hcutoff":[["n"],1,["n"],1],"hp":[["n"],1,["n"],1],"hpf":[["n"],1,["n"],1],"hold":[null,1,null,1],"hours":[null,1,null,1],"hpa":[null,1,null,1],"hpattack":[null,1,null,1],"hpd":[null,1,null,1],"hpdecay":[null,1,null,1],"hpe":[null,1,null,1],"hpenv":[null,1,null,1],"hpq":[null,1,null,1],"hresonance":[null,1,null,1],"hpr":[null,1,null,1],"hprelease":[null,1,null,1],"hps":[null,1,null,1],"hpsustain":[null,1,null,1],"hurry":[null,1,null,null],"hush":[null,0,null,null],"imag":[null,1,null,1],"in":[null,1,null,null],"inhabit":[null,1,null,2],"inhabitmod":[null,1,null,null],"inv":[null,0,null,1],"ir":[null,1,null,1],"iresponse":[null,1,null,1],"irand":[null,null,null,1],"irbegin":[null,1,null,1],"irspeed":[null,1,null,1],"iter":[null,1,null,2],"iterBack":[null,1,null,null],"jux":[null,1,null,null],"juxBy":[null,2,null,null],"kcutoff":[null,1,null,1],"krush":[null,1,null,1],"label":[null,1,null,1],"lastOf":[null,2,null,null],"late":[null,1,null,null],"layer":[null,null,null,null],"lbrick":[null,1,null,1],"leslie":[null,1,null,1],"lfo":[null,1,null,1],"repeatTime":[null,1,null,1],"linger":[null,1,null,null],"lock":[null,1,null,1],"loop":[null,1,null,1],"loopAt":[null,1,null,2],"loopBegin":[null,1,null,1],"loopb":[null,1,null,1],"loopEnd":[null,1,null,1],"loope":[null,1,null,1],"lpa":[null,1,null,1],"lpattack":[null,1,null,1],"lpd":[null,1,null,1],"lpdecay":[null,1,null,1],"lpe":[null,1,null,1],"lpenv":[null,1,null,1],"lpq":[["n"],1,["n"],1],"resonance":[["n"],1,["n"],1],"lpr":[null,1,null,1],"lprelease":[null,1,null,1],"lps":[null,1,null,1],"lpsustain":[null,1,null,1],"lrate":[null,1,null,1],"lsize":[null,1,null,1],"midibend":[null,1,null,1],"midichan":[null,1,null,1],"midicmd":[null,1,null,1],"midimap":[null,1,null,1],"midiport":[null,1,null,1],"miditouch":[null,1,null,1],"minutes":[null,1,null,1],"mix":[null,1,null,null],"mode":[["s"],1,["s"],1],"mtranspose":[null,1,null,1],"mul":[null,1,null,null],"n":[["n"],1,["n"],1],"noise":[null,1,null,1],"note":[null,1,null,1],"nrpnn":[null,1,null,1],"nrpv":[null,1,null,1],"nudge":[null,1,null,1],"octave":[null,1,null,1],"octaveR":[null,1,null,1],"octaves":[null,1,null,1],"octer":[null,1,null,1],"octersub":[null,1,null,1],"octersubsub":[null,1,null,1],"off":[null,2,null,3],"offset":[["n"],1,["n"],1],"orbit":[["n"],1,["n"],1],"oschost":[null,1,null,1],"oscport":[null,1,null,1],"outline":[null,null,null,1],"overgain":[null,1,null,1],"overshape":[null,1,null,1],"p":[null,1,null,null],"palindrome":[null,0,null,1],"pan":[["n"],1,["n"],1],"panchor":[null,1,null,1],"panorient":[null,1,null,1],"panspan":[null,1,null,1],"pansplay":[null,1,null,1],"panwidth":[null,1,null,1],"partials":[null,1,null,1],"patt":[null,1,null,1],"pattack":[null,1,null,1],"pcurve":[null,1,null,1],"pdec":[null,1,null,1],"pdecay":[null,1,null,1],"penv":[null,1,null,1],"ph":[null,1,null,1],"phaser":[null,1,null,1],"phaserrate":[null,1,null,1],"phasdp":[null,1,null,1],"phaserdepth":[null,1,null,1],"phd":[null,1,null,1],"phasercenter":[null,1,null,1],"phc":[null,1,null,1],"phasersweep":[null,1,null,1],"phs":[null,1,null,1],"pick":[null,1,null,2],"pickF":[null,2,null,3],"pickmod":[null,1,null,null],"pickmodF":[null,2,null,null],"pitchJump":[null,1,null,1],"pitchJumpTime":[null,1,null,1],"play":[null,0,null,null],"ply":[null,1,null,null],"plyForEach":[null,2,null,null],"plyWith":[null,2,null,null],"polyTouch":[null,1,null,1],"postgain":[null,1,null,1],"prel":[null,1,null,1],"prelease":[null,1,null,1],"press":[null,0,null,0],"pressBy":[null,1,null,2],"progNum":[null,1,null,1],"psus":[null,1,null,1],"psustain":[null,1,null,1],"pw":[null,1,null,1],"pwrate":[null,1,null,1],"pwsweep":[null,1,null,1],"randAt":[null,null,null,2],"randWith":[null,null,null,1],"randrun":[null,null,null,1],"range":[null,2,null,null],"rate":[null,1,null,1],"rdim":[null,1,null,1],"roomdim":[null,1,null,1],"real":[null,1,null,1],"ref":[null,null,null,1],"rel":[["n"],1,["n"],1],"release":[["n"],1,["n"],1],"repeatCycles":[null,1,null,2],"colour":[null,1,null,2],"replicate":[null,null,null,2],"reset":[null,1,null,null],"restart":[null,1,null,null],"rev":[null,0,null,null],"rfade":[null,1,null,1],"roomfade":[null,1,null,1],"rib":[null,2,null,3],"ribbon":[null,2,null,null],"ring":[null,1,null,1],"ringdf":[null,1,null,1],"ringf":[null,1,null,1],"rlp":[null,1,null,1],"roomlp":[null,1,null,1],"room":[["n"],1,["n"],1],"roomsize":[["n"],1,["n"],1],"rsize":[["n"],1,["n"],1],"size":[["n"],1,["n"],1],"sz":[["n"],1,["n"],1],"rootNotes":[null,1,null,null],"s":[["s"],1,["s"],1],"sound":[["s"],1,["s"],1],"s_taperlist":[null,1,null,null],"shrinklist":[null,1,null,2],"scale":[null,1,null,1],"scaleTranspose":[null,1,null,null],"scram":[null,1,null,1],"scrub":[null,1,null,null],"seconds":[null,1,null,1],"segment":[null,1,null,null],"semitone":[null,1,null,1],"seqPLoop":[null,null,null,null],"setCompat":[null,null,null,1],"setcpm":[null,null,null,1],"setcps":[null,null,null,1],"shape":[["n"],1,["n"],1],"slice":[null,2,null,3],"slide":[null,1,null,1],"slow":[null,1,null,2],"slowcat":[null,null,null,null],"slowcatPrime":[null,null,null,null],"smear":[null,1,null,1],"someCycles":[null,1,null,null],"sometimesBy":[null,2,null,3],"songPtr":[null,1,null,1],"source":[null,1,null,1],"src":[null,1,null,1],"spectrum":[null,0,null,null],"speed":[["n"],1,["n"],1],"spiral":[null,0,null,null],"splice":[null,2,null,null],"spread":[null,1,null,1],"squeeze":[null,null,null,2],"squiz":[null,1,null,1],"stack":[null,null,null,null],"polyrhythm":[null,null,null,null],"pr":[null,null,null,null],"steady":[null,null,null,1],"stepsPerOctave":[null,1,null,1],"stop":[null,null,null,0],"stretch":[null,1,null,1],"striate":[null,1,null,2],"struct":[null,1,null,2],"stut":[null,3,null,null],"suggestName":[null,null,null,2],"superimpose":[null,null,null,null],"sus":[["n"],1,["n"],1],"sustain":[["n"],1,["n"],1],"sustainpedal":[null,1,null,1],"swing":[null,1,null,null],"sysexdata":[null,1,null,1],"sysexid":[null,1,null,1],"transpose":[null,1,null,null],"tremolo":[null,1,null,1],"trem":[null,1,null,1],"tremolodepth":[null,1,null,1],"tremdepth":[null,1,null,1],"tremolophase":[null,1,null,1],"tremphase":[null,1,null,1],"tremoloshape":[null,1,null,1],"tremshape":[null,1,null,1],"tremoloskew":[null,1,null,1],"tremskew":[null,1,null,1],"tremolosync":[null,1,null,1],"tremsync":[null,1,null,1],"triode":[null,1,null,1],"tscope":[null,0,null,null],"tsdelay":[null,1,null,1],"uid":[null,1,null,1],"undegradeBy":[null,1,null,null],"undegradeBySeed":[null,2,null,null],"unison":[null,1,null,1],"unit":[null,1,null,1],"v":[null,1,null,1],"vib":[null,1,null,1],"vibrato":[null,1,null,1],"val":[null,1,null,1],"velocity":[null,1,null,1],"vibmod":[null,1,null,1],"vmod":[null,1,null,1],"voice":[null,1,null,1],"voicing":[null,0,null,1],"voicings":[null,1,null,null],"vowel":[null,1,null,1],"warp":[null,1,null,1],"wavetableWarp":[null,1,null,1],"warpatt":[null,1,null,1],"warpattack":[null,1,null,1],"warpdc":[null,1,null,1],"warpdec":[null,1,null,1],"warpdecay":[null,1,null,1],"warpdepth":[null,1,null,1],"warpenv":[null,1,null,1],"warpmode":[null,1,null,1],"wavetableWarpMode":[null,1,null,1],"warprate":[null,1,null,1],"warprel":[null,1,null,1],"warprelease":[null,1,null,1],"warpshape":[null,1,null,1],"warpskew":[null,1,null,1],"warpsus":[null,1,null,1],"warpsustain":[null,1,null,1],"warpsync":[null,1,null,1],"waveloss":[null,1,null,1],"wavetablePhaseRand":[null,1,null,1],"wtphaserand":[null,1,null,1],"wavetablePosition":[null,1,null,1],"wt":[null,1,null,1],"wchoose":[null,null,null,null],"wchooseCycles":[null,null,null,null],"wrandcat":[null,null,null,null],"whenmod":[null,3,null,null],"within":[null,3,null,4],"wtatt":[null,1,null,1],"wtattack":[null,1,null,1],"wtdc":[null,1,null,1],"wtdec":[null,1,null,1],"wtdecay":[null,1,null,1],"wtdepth":[null,1,null,1],"wtenv":[null,1,null,1],"wtrate":[null,1,null,1],"wtrel":[null,1,null,1],"wtrelease":[null,1,null,1],"wtshape":[null,1,null,1],"wtskew":[null,1,null,1],"wtsus":[null,1,null,1],"wtsustain":[null,1,null,1],"wtsync":[null,1,null,1],"xfade":[null,null,null,3],"xsdelay":[null,1,null,1],"zcrush":[null,1,null,1],"zdelay":[null,1,null,1],"zmod":[null,1,null,1],"znoise":[null,1,null,1],"zoom":[null,2,null,null],"zrand":[null,1,null,1],"zzfx":[null,1,null,1]};
@@ -0,0 +1,450 @@
1
+ # How RIFF was built: clean-room method and provenance
2
+
3
+ RIFF is an MIT-licensed music engine that runs code written for Strudel and
4
+ gives the same events. Strudel is AGPL-3.0. This document explains how RIFF
5
+ was written without copying Strudel, and what in the repository supports each
6
+ claim. It is meant for users, other developers and anyone reviewing the
7
+ licence, including a lawyer.
8
+
9
+ **This is not legal advice.** It is a factual record of method and evidence.
10
+ Where something has not been verified, it says so.
11
+
12
+ Status of the numbers: they were taken on 18 Nov 2026 at commit `d6d386e`
13
+ unless stated otherwise. File paths are repository paths. The npm package
14
+ ships this document but not most of the files it cites (specs, fixtures,
15
+ tools); those are in the source repository.
16
+
17
+ Contents:
18
+
19
+ 1. Why a clean room
20
+ 2. The method
21
+ 3. The gates and the proof
22
+ 4. The lab
23
+ 5. Provenance in the git history
24
+ 6. Dependencies
25
+ 7. Limits and caveats
26
+ 8. How to reproduce the checks
27
+
28
+ ---
29
+
30
+ ## 1. Why a clean room
31
+
32
+ ### Strudel's licence
33
+
34
+ From `vision.md`, section "The licence facts" (checked 18 Nov 2026):
35
+
36
+ - Strudel was never MIT. Its first commit (`38b5a0d5`, 22 Jan 2022) was
37
+ GPL-3.0-or-later. It moved to AGPL-3.0 on 27 Apr 2022 (`9ca49c58`). No
38
+ permissively licensed version exists to fork.
39
+ - The Strudel packages with AGPL code that RIFF replaces: `@strudel/core`,
40
+ `mini`, `tonal`, `transpiler`, `draw`, `codemirror`, `web`, `webaudio` and
41
+ `superdough`.
42
+ - Strudel is a port of Tidal Cycles (GPL-3.0). Tidal's code is off limits for
43
+ the same reason.
44
+
45
+ Using any of that code in RIFF would make RIFF a derivative work under the
46
+ (A)GPL. So RIFF uses none of it.
47
+
48
+ ### What copyright protects, and what it does not
49
+
50
+ Copyright protects code and text: source files, comments, documentation, data
51
+ files. It does not protect a programming language, an interface or the
52
+ behaviour of a program. `vision.md` cites:
53
+
54
+ - EU Software Directive 2009/24/EC, article 1(2) (ideas and principles behind
55
+ an interface are not protected);
56
+ - CJEU, *SAS Institute v World Programming Ltd*, C-406/10 (functionality,
57
+ programming language and data file formats are not protected);
58
+ - US, *Google LLC v. Oracle America, Inc.* (2021) (reimplementing an API's
59
+ declarations was fair use).
60
+
61
+ These are the sources the project relied on. Whether they apply to a given
62
+ use of RIFF is a legal question this document does not answer.
63
+
64
+ ### What RIFF copies and what it does not
65
+
66
+ RIFF copies Strudel's **interface and behaviour**:
67
+
68
+ - the names and signatures of the public functions user code calls;
69
+ - the mini-notation syntax;
70
+ - the event output (which events, at which times, with which values).
71
+
72
+ RIFF copies **none of Strudel's code, comments, documentation text or data
73
+ files** (`vision.md`, `CONTRIBUTING.md`).
74
+
75
+ ---
76
+
77
+ ## 2. The method
78
+
79
+ The rules are in `CONTRIBUTING.md` and `vision.md` ("How compatibility stays
80
+ legal"). Plan items 0.1 to 0.4 in `implementation-plan.md` set them up before
81
+ any engine code was written (see section 5).
82
+
83
+ ### 2.1 Two roles
84
+
85
+ Every task is done in exactly one role. A person or agent who has held the
86
+ spec-writer role on a topic does not implement that topic
87
+ (`CONTRIBUTING.md`).
88
+
89
+ **Spec writer (S).** May:
90
+
91
+ - install Strudel and run it as a black box through its public API;
92
+ - read Strudel's public documentation on strudel.cc;
93
+ - write behaviour specs in `spec/` in their own words;
94
+ - record golden fixtures in `test/fixtures/` with `tools/oracle/`, and write
95
+ corpus programs in `corpus/`.
96
+
97
+ May not:
98
+
99
+ - open Strudel's source code: the Codeberg or GitHub repositories, the files of
100
+ any `@strudel/*` npm package, unpacked bundles or source maps;
101
+ - copy documentation text, comments, examples or data tables from Strudel or
102
+ Tidal Cycles into `spec/`.
103
+
104
+ **Implementer (I).** Works from `spec/`, `test/fixtures/` and `corpus/` only.
105
+ May not open, read, grep, decompile or ask a tool to summarise Strudel's
106
+ repositories or forks, `node_modules/@strudel/*` anywhere (including inside
107
+ the oracle container), any copy of the Strudel bundle, or Tidal Cycles'
108
+ source. When a spec is unclear, the implementer asks for a spec change or a
109
+ new fixture; they never look at how Strudel does it.
110
+
111
+ Which role did which work is recorded in `docs/decisions.md`: entry headings
112
+ name the branch and, for most later entries, the role, for example
113
+ "Tier 2 combinator specs (S, branch s1-spec)" and "Tier 2 batch 1:
114
+ combinators, linger, arp, transpose (I, branch t2-funcs, plan 7.1a)".
115
+
116
+ ### 2.2 The oracle is a black-box test tool
117
+
118
+ `tools/oracle/` runs real Strudel 1.2.5 (`@strudel/core`, `mini`, `tonal`,
119
+ `transpiler`, pinned in `tools/oracle/package-lock.json`) and records what it
120
+ outputs. How it is kept apart from RIFF:
121
+
122
+ - It runs only in a throwaway `node:22-alpine` container (`tools/oracle/run.sh`,
123
+ `--rm`). `npm ci` runs inside the container; no `node_modules` is created in
124
+ the repository and none is committed (`CONTRIBUTING.md`).
125
+ - It evaluates programs through the public API only: `evalScope(...)`, then
126
+ `evaluate(code)`, then `pattern.queryArc(c, c + 1)` per cycle
127
+ (`tools/oracle/README.md`, "How a program is evaluated").
128
+ - Nothing in `src/` imports it. The package entry point is
129
+ `"exports": { ".": "./src/index.js" }`.
130
+ - It is not in the npm package. `package.json` `files` is an allow-list:
131
+ `src/`, `data/`, `docs/clean-room.md`, `LICENSE`, `README.md`. `npm pack
132
+ --dry-run` on 18 Nov 2026 listed no file under `tools/`, `test/`, `corpus/`,
133
+ `spec/` or `lab/` (see `docs/release-checklist.md`).
134
+
135
+ The same container pattern, with the same rule, is used by three other test
136
+ tools that install Strudel packages: the similarity gate (`tools/similarity/`),
137
+ the API inventory (`tools/inventory/`, which lists Strudel's public names by
138
+ loading the packages and enumerating the global scope; its header says it
139
+ "never reads package source text"), and the browser parity harness
140
+ (`test/browser/parity/`, Playwright image). Each `package.json` there is
141
+ `"private": true` and states that it is never imported by RIFF.
142
+
143
+ ### 2.3 Own names inside
144
+
145
+ Only the public API that user code calls keeps Strudel's names (for example
146
+ `note`, `s`, `stack`, `initStrudel`, `evaluate`). Internal modules, classes
147
+ and helpers have RIFF's own names. The product is never called Strudel
148
+ (`CONTRIBUTING.md`, "Own names inside"). The word "Strudel" appears in 16 of
149
+ the files under `src/` (35 times on 18 Nov 2026): in comments that describe
150
+ compatibility and in public names such as `initStrudel`.
151
+
152
+ ### 2.4 Specs in our own words
153
+
154
+ `spec/` holds the behaviour specs: `time.md`, `mini.md`, `ops.md`,
155
+ `random.md`, `transpile.md`, `samples.md`, `sound.md`, `integration.md`, and 83
156
+ files under `spec/functions/`. They describe behaviour as observed from the
157
+ outside (fixtures, black-box renders, public docs). They do not paste
158
+ Strudel's documentation; `CONTRIBUTING.md` forbids it. `spec/sound.md` opens
159
+ with "Behaviour spec in our own words, from black-box offline renders of
160
+ Strudel".
161
+
162
+ Whether every spec sentence is free of copied documentation text has not been
163
+ checked by a tool. The similarity gate covers code, not prose (section 7).
164
+
165
+ ### 2.5 Fixtures are output data
166
+
167
+ A fixture (`test/fixtures/<set>/<name>.json`) holds a program from `corpus/`,
168
+ the cycle range, and the events Strudel returned (`haps`: begin, end and value
169
+ of each event as exact fractions), or the error Strudel raised. Some also hold
170
+ the output of Strudel's transpiler (`transpiled`) or the `cps` and stubs the
171
+ program called. This is the output of running a program, not Strudel's code.
172
+
173
+ The corpus programs are RIFF's own: SAAI's genre templates and recorded LLM
174
+ outputs (`corpus/saai/`, 177 programs), and programs written by spec writers
175
+ per area. No corpus file mentions strudel.cc or says it was copied from
176
+ Strudel's documentation (`grep -rli "strudel\.cc" corpus` finds nothing).
177
+ Fixtures and corpus are not in the npm package.
178
+
179
+ ### 2.6 How LLM implementers were briefed
180
+
181
+ Most of RIFF was written by LLM agents. Every implementer brief starts from
182
+ `docs/builder-brief-template.md`, whose clean-room block is fixed text
183
+ ("do not shorten"). Quoted as it is in the repository:
184
+
185
+ > You are an **implementer**. RIFF is a clean-room, MIT-licensed
186
+ > reimplementation of Strudel's behaviour. You work only from:
187
+ >
188
+ > - `spec/` (behaviour specs in our own words),
189
+ > - `test/fixtures/` (golden event lists recorded from the oracle),
190
+ > - `corpus/` (the programs those fixtures were recorded from),
191
+ > - `vision.md`, `implementation-plan.md`, `CONTRIBUTING.md`, and RIFF's own
192
+ > `src/`.
193
+ >
194
+ > You must **never** open, read, grep, fetch, decompile or ask any tool to
195
+ > summarise Strudel or Tidal source code. Forbidden paths and sources:
196
+ >
197
+ > - `/nebula/apps/saai/public/vendor/strudel/` (the bundle SAAI ships);
198
+ > - any `node_modules/@strudel/*`, including inside the `tools/oracle/`
199
+ > container;
200
+ > - codeberg.org/uzu/strudel, github.com/tidalcycles/strudel, any fork,
201
+ > mirror, unpkg/jsdelivr/esm.sh URL or source map of `@strudel/*`;
202
+ > - Tidal Cycles' source code;
203
+ > - strudel.cc pages other than to confirm a public function name (spec
204
+ > writers read the docs; you do not need to).
205
+ >
206
+ > Do not write code from memory of how Strudel is implemented. If you recall
207
+ > Strudel's internals, do not use them: derive behaviour from the spec and
208
+ > the fixtures. Internal names are our own; only the public user-facing API
209
+ > keeps Strudel's names.
210
+ >
211
+ > **Zero dependencies.** No npm package in `src/`, no build step: plain ES
212
+ > modules. Tests use Node's built-in `node:test`.
213
+ >
214
+ > If the spec or fixtures do not settle a behaviour, stop and report the
215
+ > question; the spec writer adds a fixture. Do not look it up.
216
+
217
+ The briefs themselves were messages to agents and are not stored in the
218
+ repository. That each brief contained this block is a process claim; the
219
+ repository cannot prove it (section 7).
220
+
221
+ ---
222
+
223
+ ## 3. The gates and the proof
224
+
225
+ ### 3.1 Fixtures and how they are compared
226
+
227
+ Counted on 18 Nov 2026 (`test/fixtures/`, 1 326 files):
228
+
229
+ | kind | count | how it is compared |
230
+ |---|---|---|
231
+ | exact event lists | 1 175 | hap by hap: same `whole`, `part` (exact fractions) and `value`, same order |
232
+ | random (statistical) | 105 | per-cycle event counts and value sets, not the exact sequence |
233
+ | expected errors | 46 | RIFF must reject the program as Strudel did |
234
+
235
+ By set: `functions` 754, `saai` 177, `mini` 139, `ops` 131, `transpile` 81,
236
+ `time` 40, `integration` 4.
237
+
238
+ The comparison code is `lab/compare.js` (`compareExact`, `compareRandom`),
239
+ used by both `test/fixtures.test.js` and the lab. Random functions are exempt
240
+ from exact matching by an operator decision (`vision.md`, L1 row, 18 Nov
241
+ 2026): they keep the same probabilities and stay deterministic per seed, but
242
+ their sequence may differ.
243
+
244
+ Result of `node --test test/fixtures.test.js` at `d6d386e`:
245
+
246
+ ```
247
+ fixtures: 1326 total, 1166 runnable; skipped: 9 need a later epic, 0 random,
248
+ 0 no pattern; 105 random (statistical), 46 expected errors, 0 broken
249
+ tests 1389, pass 1388, fail 0, skipped 1
250
+ ```
251
+
252
+ The 9 skipped fixtures belong to effects that are specified but not built yet
253
+ (vowel, phaser, vibrato, tremolo; spec commits `df9c857`, `4dc4b49`,
254
+ `f25f5d5`).
255
+
256
+ ### 3.2 Compatibility levels L1 to L4
257
+
258
+ Defined in `vision.md`, "What fully compatible means, measured":
259
+
260
+ | level | promise | measured by | status (18 Nov 2026) |
261
+ |---|---|---|---|
262
+ | L1 Events | `queryArc` returns the same events as Strudel | golden fixtures, 0–16 cycles each | 0 fixture failures (3.1) |
263
+ | L2 Output | the synth receives the same parameters at the same audio-clock times | scheduler log vs Strudel's `onTrigger` log, browser parity harness | 101 / 102 programs |
264
+ | L3 Sound | each synth, effect and sample bank sounds the same | offline renders in both engines: loudness ±1 dB, spectral centroid ±5 %, onsets ±1 ms; plus an A/B listen | 94 / 102 programs by measurement; A/B listen not done |
265
+ | L4 Integration | SAAI runs on RIFF with only its import path changed | the operator checks by hand | not recorded in the repository |
266
+
267
+ L2 and L3 figures are from `docs/parity-report.md`, row "p3-sound (18 Nov,
268
+ after)". They were not re-run for this document. The one L2 miss is
269
+ `saai-song`: one hi-hat 13 µs (0.6 sample) off by float rounding. The L3
270
+ misses are listed per program in the same report.
271
+
272
+ ### 3.3 The code-similarity gate
273
+
274
+ **Why.** An LLM implementer may have seen Strudel's source in training and
275
+ could reproduce it from memory without opening it. The gate checks the
276
+ result, independent of process (`vision.md`, rule 3).
277
+
278
+ **What it compares.** `tools/similarity/check.sh` runs
279
+ `tools/similarity/compare.mjs` in a throwaway `node:22-alpine` container. It
280
+ installs the reference packages from `tools/similarity/package-lock.json`
281
+ (`@strudel/codemirror`, `core`, `draw`, `mini`, `tonal`, `transpiler`, `web`,
282
+ `webaudio` and `superdough`, versions 1.2.5/1.2.6), tokenises them and RIFF's
283
+ `src/` and `lab/`, drops whitespace and comments, and keeps identifiers,
284
+ literals and punctuation verbatim. It hashes runs of tokens and reports
285
+ matches. It never prints reference code: output names RIFF file and line
286
+ ranges and the reference package name only.
287
+
288
+ **Thresholds** (defaults in `compare.mjs`, `CONTRIBUTING.md`):
289
+
290
+ - any shared run of **40 or more tokens** fails;
291
+ - an overall share of **2 % or more** of RIFF tokens inside shared 20-token
292
+ shingles fails.
293
+
294
+ **Self-test.** `check.sh --selftest` copies a real 100-token function from
295
+ `@strudel/core` and checks that the gate fails on it, and passes on an empty
296
+ directory and on a sample of own code.
297
+
298
+ **When it runs.** Not inside `npm test`: `tools/test.mjs` runs unit tests and
299
+ fixtures only, within a 10-second budget. The gate runs once per batch of
300
+ merged work, by the test-runner, before a push (`implementation-plan.md`,
301
+ testing rules: "one test-runner per batch runs `npm test` plus the similarity
302
+ gate"; `CONTRIBUTING.md`). Batch runs before 18 Nov 2026 were not written
303
+ down; from now on each run is added to `docs/similarity-report.md`.
304
+
305
+ **Result on 18 Nov 2026** (commit `d6d386e`, full record in
306
+ `docs/similarity-report.md`):
307
+
308
+ - 0 clones of 40 or more tokens; overall 0.28 % (limit < 2 %); PASS.
309
+ - Self-test: copied code fails, empty and own code pass.
310
+ - Longest shared run: 39 tokens (`src/pattern.js:31-38`, the opening of the
311
+ public `queryArc` method). Other runs of 20 to 34 tokens are short state
312
+ classes, note-name tables and similar idioms.
313
+
314
+ ---
315
+
316
+ ## 4. The lab
317
+
318
+ `lab/` is a static web page for checking RIFF by hand: one item per public
319
+ name, grouped by feature area, each with an example program
320
+ (`lab/catalog.json`, built by `npm run lab:catalog`). It is in the repository,
321
+ not in the npm package.
322
+
323
+ Each item shows one status (`lab/lab.js`):
324
+
325
+ | status | meaning |
326
+ |---|---|
327
+ | `not implemented` | `src/index.js` does not export the name (or `Pattern.prototype` lacks the method) |
328
+ | `matches` | RIFF's events for the example equal the oracle fixture (or both reject the program) |
329
+ | `mismatch` | they differ, or RIFF throws |
330
+ | `random (statistical)` | the example is random; compared statistically |
331
+ | `no fixture` | there is no recorded Strudel output for this example |
332
+
333
+ The lab uses the same `lab/compare.js` as the test suite. To verify a claim
334
+ yourself: run `npm run lab`, open <http://localhost:8080/>, pick a function,
335
+ read its status, change the example and listen. Play needs a browser with Web
336
+ Audio.
337
+
338
+ The lab compares against recorded fixtures. It does not run Strudel.
339
+
340
+ ---
341
+
342
+ ## 5. Provenance in the git history
343
+
344
+ The history shows the clean-room setup and the specs and fixtures before the
345
+ engine code. All commits below are on 18 Nov 2026 (CET).
346
+
347
+ | time | commit | what |
348
+ |---|---|---|
349
+ | 11:23:25 | `9f75c85` | Epic 0: licence, clean-room rules, oracle (`tools/oracle/`), first corpus and 225 fixtures. No engine code. |
350
+ | 11:23:39 | `e6b297b` | npm packaging; first file under `src/` (a 2-line `src/index.js`). |
351
+ | 11:25:02 | `5029bac` | Similarity gate (0.4) and API inventory (1.1). |
352
+ | 11:37:16 | `220e94b` | Specs: transpiler, samples, integration surface. |
353
+ | 11:41:52 | `54ec6a7` | Tier 1 function specs, `random.md` and oracle fixtures. |
354
+ | 11:43:36 | `19ac458` | Specs `time`, `mini`, `ops` with corpus and fixtures. |
355
+ | 11:53:23 | `2452465` | First engine code: fractions, spans, haps, Pattern (plan 2.1, 2.2). Touches `src/`, `test/`, the plan; no spec or fixture. |
356
+ | 12:10:18 | `54ae637` | Mini-notation parser and transpiler, 27 minutes after the `mini.md` spec (`19ac458`). |
357
+ | 22:36–22:38 | `df9c857`, `4dc4b49`, `f25f5d5` | Latest example: vowel, phaser, vibrato, tremolo specified with fixtures and measurements; not yet implemented at `d6d386e`. |
358
+
359
+ One area went the other way: the first audio code (`538fb92`, 12:21) came
360
+ before the sound spec (`spec/sound.md`, `32b8f3d`, 15:57). The early synths
361
+ were written from the plan and general Web Audio practice; the sound spec was
362
+ then written from black-box renders, and the L3 fixes followed from it
363
+ (`docs/decisions.md`, "L3 sound parity").
364
+
365
+ To see this yourself: `git log --reverse --format='%h %ai %s'`, and for one
366
+ area `git log --reverse -- spec/mini.md` against `git log --reverse --
367
+ src/mini`.
368
+
369
+ **The decision log.** `docs/decisions.md` records each design decision with
370
+ date, branch and, for most entries, the role (S or I). Examples of what it
371
+ holds: the reasons for random functions being compared statistically, the
372
+ `won't` list, the L3 tolerances and fixes, and the independent audit fixes
373
+ ("Independent audit fixes (I, branch a1-audit)").
374
+
375
+ Caveat: git timestamps are set by the committer's machine and can be changed.
376
+ They show the recorded order, not an independent timestamp. The pushes to the
377
+ project's forge give a second record; that record was not checked for this
378
+ document.
379
+
380
+ ---
381
+
382
+ ## 6. Dependencies
383
+
384
+ - **Runtime: none.** `package.json` has no `dependencies` or
385
+ `peerDependencies`. Fractions, the transpiler, the mini-notation parser and
386
+ the scale and chord tables are RIFF's own code. `src/` is plain ES modules
387
+ with no build step.
388
+ - **Tests:** Node's built-in `node:test` only (`npm test`).
389
+ - **Test tools only, never in the package, installed only inside throwaway
390
+ containers:**
391
+ - `tools/oracle/`: `@strudel/core`, `mini`, `tonal`, `transpiler` 1.2.5;
392
+ - `tools/similarity/`: the nine reference packages listed in 3.3;
393
+ - `tools/inventory/`: Strudel packages, to list public names;
394
+ - `test/browser/parity/`: `@strudel/*` 1.2.5, `esbuild`, `playwright-core`,
395
+ in the image `mcr.microsoft.com/playwright:v1.62.1-noble`.
396
+ - The host editor (CodeMirror, MIT) is supplied by the host app, not by RIFF.
397
+
398
+ ---
399
+
400
+ ## 7. Limits and caveats
401
+
402
+ - **Training data.** The implementers were LLM agents. They may have seen
403
+ Strudel's source during training. The rules forbid using such memory, but a
404
+ model cannot prove what it did not recall. This is why the similarity gate
405
+ exists.
406
+ - **What the gate does not catch.** It matches exact token sequences. A copy
407
+ with renamed variables or reordered statements would not be found. A
408
+ structural (AST) or renamed-identifier comparison has not been run. Prose
409
+ (specs, comments, docs) is not compared.
410
+ - **Process claims.** Role separation and the content of briefs are process
411
+ rules. The repository records them (`CONTRIBUTING.md`, the template, the
412
+ role labels in `docs/decisions.md`), but cannot prove that every agent
413
+ followed them. Spec writers and implementers were separate agent sessions
414
+ with separate contexts, often running the same underlying model.
415
+ - **Not verified yet:** the A/B listen by the operator (L3 "done when",
416
+ `implementation-plan.md`); playback on an iPhone and an Android phone (plan
417
+ 8.10, marked open after the audit); L4 integration in SAAI as a recorded
418
+ check.
419
+ - **Not implemented on purpose:** 144 public names (14 Tier 2 + 130 Tier 3)
420
+ are marked `won't` in `spec/inventory.csv`, each with a reason: MIDI, OSC,
421
+ mouse and keyboard input, editor CSS, internal helpers, names not callable in
422
+ Strudel 1.2.5 (`docs/decisions.md`; `spec/tier3-triage.md`). A count of the
423
+ CSV on 18 Nov 2026 finds 164 rows whose status starts with `won't`; aliases
424
+ share a name, which is why rows outnumber names.
425
+ - **Known gaps:** 9 L1 fixtures for effects not built yet (3.1); 1 L2 miss
426
+ and 8 L3 misses (3.2); RIFF's random sequences differ from Strudel's by
427
+ design.
428
+ - **Legal status.** No lawyer has reviewed RIFF. `vision.md` notes that a
429
+ short review is cheap insurance if RIFF is ever sold.
430
+
431
+ ---
432
+
433
+ ## 8. How to reproduce the checks
434
+
435
+ From a clone of the repository, with Node 20 or later and Docker:
436
+
437
+ ```sh
438
+ npm test # unit tests + fixtures, 10 s budget
439
+ node --test test/fixtures.test.js # fixtures only; prints the summary line
440
+ sh tools/similarity/check.sh # similarity gate over src/ and lab/
441
+ sh tools/similarity/check.sh --selftest # proves the gate fails on a copy
442
+ sh tools/similarity/check.sh data # the generated registry data
443
+ npm pack --dry-run # what the npm package contains
444
+ npm run lab # the lab on http://localhost:8080/
445
+ git log --reverse --format='%h %ai %s' # the order of specs and code
446
+ ```
447
+
448
+ Re-recording fixtures from Strudel (spec-writer role only):
449
+ `tools/oracle/run.sh` (Docker). The browser parity renders (L2/L3):
450
+ `npm run parity -- all` (Docker, Playwright image; slow, run on demand).
package/package.json CHANGED
@@ -1,6 +1,71 @@
1
1
  {
2
2
  "name": "@zeeuw/riff",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0-beta.0",
4
+ "description": "RIFF (Rhythm In Functional Form): a zero-dependency live-coding music engine for the browser, compatible with Strudel code",
5
+ "license": "MIT",
6
+ "author": "Danny de Zeeuw",
7
+ "type": "module",
8
+ "sideEffects": [
9
+ "./src/index.js",
10
+ "./src/audio/index.js",
11
+ "./src/audio/offline.js",
12
+ "./src/outline.js",
13
+ "./src/extras/index.js",
14
+ "./src/extras/check.js",
15
+ "./src/extras/describe.js",
16
+ "./src/extras/editor.js",
17
+ "./src/scope.js",
18
+ "./src/combinators.js",
19
+ "./src/constructors.js",
20
+ "./src/controls.js",
21
+ "./src/draw.js",
22
+ "./src/euclid.js",
23
+ "./src/evaluate.js",
24
+ "./src/mini/index.js",
25
+ "./src/ops.js",
26
+ "./src/random.js",
27
+ "./src/signals.js",
28
+ "./src/helpers.js",
29
+ "./src/sampling.js",
30
+ "./src/stepwise.js",
31
+ "./src/structure.js",
32
+ "./src/tonal.js",
33
+ "./src/transforms.js"
34
+ ],
35
+ "exports": {
36
+ ".": "./src/index.js",
37
+ "./extras": "./src/extras/index.js",
38
+ "./package.json": "./package.json"
39
+ },
40
+ "files": [
41
+ "src/",
42
+ "data/",
43
+ "docs/clean-room.md",
44
+ "LICENSE",
45
+ "README.md"
46
+ ],
47
+ "engines": {
48
+ "node": ">=20"
49
+ },
50
+ "keywords": [
51
+ "live-coding",
52
+ "music",
53
+ "patterns",
54
+ "algorave",
55
+ "web-audio",
56
+ "strudel-compatible",
57
+ "mini-notation"
58
+ ],
59
+ "scripts": {
60
+ "test": "node tools/test.mjs",
61
+ "pack:check": "npm pack --dry-run",
62
+ "lab": "node lab/server.mjs",
63
+ "lab:catalog": "node tools/lab/build-catalog.mjs",
64
+ "registry": "node tools/registry/build.mjs && node tools/registry/prompt.mjs",
65
+ "bench": "node tools/bench/query.mjs",
66
+ "parity": "sh test/browser/parity/run.sh"
67
+ },
68
+ "publishConfig": {
69
+ "access": "public"
70
+ }
71
+ }