@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/sound-design/tools/vst3host/session.h

@@ -0,0 +1,241 @@
+// One plugin, loaded and running offline: no audio device, no window, no JUCE. A JUCE host cannot load every JUCE plugin (an allocator clash across
+// the boundary aborted one inside its own parameter loader), and every audio path through an operating system can fail differently, one of them by
+// returning silence instead of an error. A renderer that never opens a device has none of those failures, and runs faster than real time.
+#pragma once
+
+#include "host_events.h"
+#include "options.h"
+
+#include "pluginterfaces/vst/ivstaudioprocessor.h"
+#include "pluginterfaces/vst/ivstcomponent.h"
+#include "pluginterfaces/vst/ivsteditcontroller.h"
+#include "pluginterfaces/vst/ivstprocesscontext.h"
+#include "public.sdk/source/common/memorystream.h"
+#include "public.sdk/source/vst/hosting/hostclasses.h"
+#include "public.sdk/source/vst/hosting/module.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdio>
+#include <deque>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace vst3host {
+
+inline std::string titleOf (const Vst::ParameterInfo& info) {
+    std::string name;
+    for (int k = 0; k < 128 && info.title[k]; ++k) name += (char) info.title[k];
+    return name;
+}
+
+class Session {
+public:
+    Session (const Options& options) : sampleRate (options.sampleRate), block (options.block) {}
+
+    // Loads the module and wires the two halves. An empty return is success; anything else is why it failed.
+    std::string open (const std::string& path) {
+        std::string error;
+        module = VST3::Hosting::Module::create (path, error);
+        if (! module) return "load failed: " + error;
+        auto factory = module->getFactory();
+        for (auto& info : factory.classInfos()) {
+            if (info.category() != kVstAudioEffectClass) continue;
+            component = factory.createInstance<Vst::IComponent> (info.ID()).take();
+            break;
+        }
+        if (! component) return "no audio class";
+        host = new Vst::HostApplication();
+        if (component->initialize (host) != kResultOk) return "initialize failed";
+        component->queryInterface (Vst::IAudioProcessor::iid, (void**) &processor);
+        if (! processor) return "no IAudioProcessor";
+        openController (factory);
+        return {};
+    }
+
+    void printParameters (bool withValues) {
+        if (! controller) return void (std::printf ("  no controller, so no parameters to read\n"));
+        const int32 count = controller->getParameterCount();
+        std::printf ("  %d parameters\n", count);
+        for (int32 i = 0; i < count; ++i) {
+            Vst::ParameterInfo info {};
+            if (controller->getParameterInfo (i, info) != kResultOk) continue;
+            if (withValues) std::printf ("    %-40s %.6f\n", titleOf (info).c_str(), controller->getParamNormalized (info.id));
+            else std::printf ("    %5d  id %-10u  %s\n", i, info.id, titleOf (info).c_str());
+        }
+    }
+
+    // Every output bus is activated and given a buffer: a plugin handed fewer buses than it declares may write nothing at all.
+    std::string start() {
+        Vst::ProcessSetup setup {};
+        setup.processMode = Vst::kOffline;
+        setup.symbolicSampleSize = Vst::kSample32;
+        setup.maxSamplesPerBlock = block;
+        setup.sampleRate = sampleRate;
+        if (processor->setupProcessing (setup) != kResultOk) return "setupProcessing failed";
+        activateBuses();
+        component->setActive (true);
+        processor->setProcessing (true);
+        prepareBuffers();
+        return {};
+    }
+
+    void stop() {
+        processor->setProcessing (false);
+        component->setActive (false);
+    }
+
+    // Renders this long. Events and parameter changes go in the first block.
+    void run (double seconds, bool keep) {
+        const int64 total = (int64) (seconds * sampleRate);
+        for (int64 done = 0; done < total; done += block) {
+            const auto count = (int32) std::min<int64> (block, total - done);
+            processBlock (count);
+            if (! keep) continue;
+            left.insert (left.end(), buffers[0].begin(), buffers[0].begin() + count);
+            right.insert (right.end(), buffers[1].begin(), buffers[1].begin() + count);
+        }
+    }
+
+    // Both routes. A firmware emulator's parameters may talk to it only through the controller, and a plain plugin reads inputParameterChanges.
+    void setParam (Vst::ParamID id, double value) {
+        if (controller) controller->setParamNormalized (id, value);
+        int32 index = 0;
+        int32 point = 0;
+        if (auto* queue = changes.addParameterData (id, index)) queue->addPoint (0, value, point);
+    }
+
+    // VST3 has no event for sysex or a program change: raw MIDI goes in a data event, which a plugin's own MIDI parser reads.
+    void sendBytes (std::vector<unsigned char> bytes) {
+        kept.push_back (std::move (bytes));
+        Vst::Event e {};
+        e.type = Vst::Event::kDataEvent;
+        e.data.type = Vst::DataEvent::kMidiSysEx;
+        e.data.size = (uint32) kept.back().size();
+        e.data.bytes = kept.back().data();
+        events.addEvent (e);
+    }
+
+    void noteOn (int pitch, int velocity) {
+        Vst::Event e {};
+        e.type = Vst::Event::kNoteOnEvent;
+        e.noteOn.pitch = (int16) pitch;
+        e.noteOn.velocity = (float) velocity / 127.0f;
+        e.noteOn.noteId = -1;
+        events.addEvent (e);
+    }
+
+    void noteOff (int pitch) {
+        Vst::Event e {};
+        e.type = Vst::Event::kNoteOffEvent;
+        e.noteOff.pitch = (int16) pitch;
+        e.noteOff.noteId = -1;
+        events.addEvent (e);
+    }
+
+    void clearKept() {
+        left.clear();
+        right.clear();
+    }
+
+    const std::vector<float>& keptLeft() const { return left; }
+    const std::vector<float>& keptRight() const { return right; }
+    Vst::IEditController* editController() { return controller; }
+    ParamChanges& reported() { return outChanges; }
+
+private:
+    // State first, then the wire: the controller mirrors the component, so it needs the state before its parameters mean anything.
+    void openController (VST3::Hosting::PluginFactory& factory) {
+        if (component->queryInterface (Vst::IEditController::iid, (void**) &controller) != kResultOk) {
+            TUID id;
+            if (component->getControllerClassId (id) == kResultOk) controller = factory.createInstance<Vst::IEditController> (VST3::UID (id)).take();
+            if (controller) controller->initialize (host);
+        }
+        if (! controller) return;
+        wireHalves();
+        MemoryStream state;
+        if (component->getState (&state) != kResultOk) return;
+        state.seek (0, IBStream::kIBSeekSet, nullptr);
+        controller->setComponentState (&state);
+    }
+
+    void wireHalves() {
+        Vst::IConnectionPoint* fromComponent = nullptr;
+        Vst::IConnectionPoint* fromController = nullptr;
+        component->queryInterface (Vst::IConnectionPoint::iid, (void**) &fromComponent);
+        controller->queryInterface (Vst::IConnectionPoint::iid, (void**) &fromController);
+        if (! fromComponent || ! fromController) return;
+        fromComponent->connect (new ConnectionProxy (fromController));
+        fromController->connect (new ConnectionProxy (fromComponent));
+    }
+
+    void activateBuses() {
+        const int32 outputs = component->getBusCount (Vst::kAudio, Vst::kOutput);
+        const int32 eventBuses = component->getBusCount (Vst::kEvent, Vst::kInput);
+        std::printf ("  buses: %d audio out, %d event in\n", outputs, eventBuses);
+        for (int32 bus = 0; bus < outputs; ++bus) component->activateBus (Vst::kAudio, Vst::kOutput, bus, true);
+        for (int32 bus = 0; bus < eventBuses; ++bus) component->activateBus (Vst::kEvent, Vst::kInput, bus, true);
+        if (component->getBusCount (Vst::kAudio, Vst::kInput) > 0) component->activateBus (Vst::kAudio, Vst::kInput, 0, true);
+    }
+
+    void prepareBuffers() {
+        const auto outputs = (size_t) std::max (1, component->getBusCount (Vst::kAudio, Vst::kOutput));
+        buffers.assign ((outputs + 1) * 2, std::vector<float> ((size_t) block, 0.0f)); // the last pair is the silent input
+        pointers.resize (outputs + 1);
+        busBuffers.assign (outputs + 1, Vst::AudioBusBuffers {});
+        for (size_t bus = 0; bus <= outputs; ++bus) {
+            pointers[bus] = { buffers[bus * 2].data(), buffers[bus * 2 + 1].data() };
+            busBuffers[bus].numChannels = 2;
+            busBuffers[bus].channelBuffers32 = pointers[bus].data();
+        }
+        context.state = Vst::ProcessContext::kPlaying | Vst::ProcessContext::kTempoValid;
+        context.sampleRate = sampleRate;
+        context.tempo = 120.0;
+        data.processMode = Vst::kOffline;
+        data.symbolicSampleSize = Vst::kSample32;
+        data.numInputs = component->getBusCount (Vst::kAudio, Vst::kInput) > 0 ? 1 : 0;
+        data.numOutputs = (int32) outputs;
+        data.inputs = data.numInputs ? &busBuffers[outputs] : nullptr;
+        data.outputs = busBuffers.data();
+        data.inputEvents = &events;
+        data.inputParameterChanges = &changes;
+        data.outputParameterChanges = &outChanges; // left null, a change a plugin's own sysex handler made stays invisible
+        data.processContext = &context;
+    }
+
+    void processBlock (int32 count) {
+        data.numSamples = count;
+        std::fill (buffers[0].begin(), buffers[0].end(), 0.0f);
+        std::fill (buffers[1].begin(), buffers[1].end(), 0.0f);
+        context.projectTimeSamples = position;
+        processor->process (data);
+        events.clear();
+        changes.clear();
+        kept.clear();
+        position += count;
+    }
+
+    double sampleRate;
+    int block;
+    VST3::Hosting::Module::Ptr module;
+    Vst::HostApplication* host = nullptr;
+    Vst::IComponent* component = nullptr;
+    Vst::IAudioProcessor* processor = nullptr;
+    Vst::IEditController* controller = nullptr;
+    std::vector<std::vector<float>> buffers;
+    std::vector<std::array<float*, 2>> pointers;
+    std::vector<Vst::AudioBusBuffers> busBuffers;
+    Vst::ProcessContext context {};
+    Vst::ProcessData data {};
+    EventList events;
+    ParamChanges changes;
+    ParamChanges outChanges;
+    std::deque<std::vector<unsigned char>> kept;
+    std::vector<float> left;
+    std::vector<float> right;
+    int64 position = 0;
+};
+
+} // namespace vst3host

package/packs/stellix/checks/no-keyboard-focus.json

@@ -0,0 +1,12 @@
+{
+  "id": "no-keyboard-focus",
+  "why": "Stellix 3a: no dropdown, button or readout ever takes keyboard focus; QWERTY always plays.",
+  "rule": ".claude/rules/stellix-deterministic-world.md",
+  "concepts": [
+    "ui"
+  ],
+  "pattern": "setWantsKeyboardFocus\\s*\\(\\s*true|grabKeyboardFocus\\s*\\(|setMouseClickGrabsKeyboardFocus\\s*\\(\\s*true",
+  "code": true,
+  "bad": "presetBox.setWantsKeyboardFocus (true);",
+  "good": "presetBox.setWantsKeyboardFocus (false);"
+}

package/packs/stellix/checks/one-seeded-random.json

@@ -0,0 +1,16 @@
+{
+  "id": "one-seeded-random",
+  "why": "Stellix rule 4: formulas by default; the only randomness is the world's one seeded generator (RANDOM, 6.6). No other random call may exist in the engine, the world or the drawing.",
+  "rule": ".claude/rules/stellix-deterministic-world.md",
+  "concepts": [
+    "cpp"
+  ],
+  "exclude": [
+    "@seeded_random",
+    "**/tests/**"
+  ],
+  "pattern": "(?<![\\w.])(?:std::)?(?:s?rand|random|drand48|lrand48|arc4random(?:_uniform)?)\\s*\\(|\\b(?:random_device|mt19937(?:_64)?|minstd_rand0?|default_random_engine|ranlux\\w+|knuth_b)\\b|\\b\\w+_distribution\\b|\\bjuce::Random\\b|(?<![\\w:])Random\\s*(?:::|\\w+\\s*[;({=])|\\bgetSystemRandom\\b|\\bSecRandomCopyBytes\\b|\\bRAND_bytes\\b",
+  "code": true,
+  "bad": "float jitter = juce::Random::getSystemRandom().nextFloat();\nstd::mt19937 g (42);\nstd::uniform_real_distribution<float> d (0, 1);\nuint32_t v = arc4random_uniform (8);",
+  "good": "float jitter = world.seeded().next01();\nauto n = randomSource.next(); int operand (int); bool israndom;\ninline float hash (int i) { return std::sin (float (i) * 12.98f) * 43758.5f; }"
+}

package/packs/stellix/checks/world-never-includes-painter.json

@@ -0,0 +1,12 @@
+{
+  "id": "world-never-includes-painter",
+  "why": "Stellix 8: the world is coordinates, not graphics. The audio side includes nothing from the painter or any GPU API; it publishes a plain-data snapshot and nothing else.",
+  "rule": ".claude/rules/stellix-world-snapshot.md",
+  "concepts": [
+    "world",
+    "audio"
+  ],
+  "pattern": "#\\s*(include|import)\\s*[<\"][^>\"]*(painter|Painter|gpu/|render/|Renderer|juce_opengl|OpenGL|Metal/|MetalKit|QuartzCore|bgfx|webgpu)[^>\"]*[>\"]",
+  "bad": "#include \"../painter/PlanetMesh.h\"",
+  "good": "#include \"WorldSnapshot.h\""
+}

package/packs/stellix/checks/world-no-libm.json

@@ -0,0 +1,15 @@
+{
+  "id": "world-no-libm",
+  "why": "libm sin/cos/exp/pow differ in the last bits between Apple, MSVC and glibc; the world must replay bit-identically on Mac and Windows. Use the house world-math functions.",
+  "rule": ".claude/rules/world-fp-determinism.md",
+  "concepts": [
+    "world"
+  ],
+  "exclude": [
+    "@world_math"
+  ],
+  "pattern": "\\bstd::(sin|cos|tan|asin|acos|atan2?|exp2?|expm1|log(2|10|1p)?|pow|sinh|cosh|tanh|hypot|cbrt)\\s*\\(|(?<![\\w:.>])(sinf?|cosf?|tanf?|atan2f?|expf?|logf?|powf?)\\s*\\(",
+  "code": true,
+  "bad": "const double a = std::sin (phase) * radius;",
+  "good": "const double a = wm::sin (phase) * radius;"
+}

package/packs/stellix/checks/world-no-unordered.json

@@ -0,0 +1,10 @@
+{
+  "id": "world-no-unordered",
+  "why": "Hash-container iteration order differs between libc++ and the MSVC STL; the world must be ordered by stable ID to replay identically on every platform.",
+  "rule": ".claude/rules/world-fp-determinism.md",
+  "concepts": ["world"],
+  "pattern": "\\bstd::unordered_(map|set|multimap|multiset)\\b",
+  "code": true,
+  "bad": "std::unordered_map<int, Moon> moonsById;",
+  "good": "std::array<Moon, kMaxMoons> moons; // ordered by stable id"
+}

package/packs/stellix/hooks/no-shipped-images.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Nothing is ever pre-rendered (Stellix spec 0.2). No image file may be added to the source or
+// resources (fonts are allowed: data, not pictures). Test output and goldens live outside them.
+// A project sets its own scope in .claude/layout.json "guards": { "images": { "guarded": [globs],
+// "allowed": [globs] } }: "guarded" replaces the code folders (["**"]: anywhere in the repo), "allowed"
+// replaces the default allowed folders (Stellix: design/reference/** and build/pictures/** only).
+//   PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): blocks writing, copying or moving an image into a guarded
+//   folder by any route (lib/writes.mjs), and a download or conversion that names one (curl, convert, sips ...).
+//   --git-staged: run from a git pre-commit hook; fails if a staged added file is an image.
+//   --selftest: proves it.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { matchesAny } from './lib/glob.mjs';
+import { codeFolders, readLayout } from './lib/layout.mjs';
+import { claudeRoot, commandLeavesProject, insideProject, relInCheckout } from './lib/project.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { bashOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const IMAGE = /\.(png|jpe?g|gif|bmp|tiff?|webp|heic|ico|icns|svg|psd|tga|exr|hdr|ktx2?|dds|astc)$/i;
+// Guarded: every code folder in the layout, plus anything that would be bundled as a resource.
+const guarded = (root) => readLayout(root).guards?.images?.guarded ?? [...new Set(['src/**', 'Resources/**', 'resources/**', 'assets/**', ...codeFolders(readLayout(root)).map((f) => `${f}/**`)])];
+const ALLOWED = ['tests/**', '**/tests/**', 'goldens/**', '**/goldens/**', 'docs/**', 'captures/**', 'build/**'];
+const allowed = (root) => readLayout(root).guards?.images?.allowed ?? ALLOWED;
+
+// A path is judged in its own checkout, so an image written into an agent worktree is caught too.
+const isBlocked = (p, base = ROOT) => {
+  const abs = resolve(base, p);
+  if (!IMAGE.test(abs) || !insideProject(abs)) return false;
+  const rel = relInCheckout(abs).replace(/^\.claude\/worktrees\/[^/]+\//, '');
+  const root = claudeRoot(abs);
+  return !rel.startsWith('.claude/') && matchesAny(rel, guarded(root)) && !matchesAny(rel, allowed(root));
+};
+
+function fail(files) {
+  process.stderr.write(
+    `BLOCKED by no-shipped-images: ${files.join(', ')}\n` +
+      'Nothing is pre-rendered: draw it in code; a picture check renders off-screen, from the app itself, into an allowed folder (guards.images.allowed in .claude/layout.json).\n',
+  );
+  return 2;
+}
+
+function gitStaged() {
+  const out = execFileSync('git', ['diff', '--cached', '--name-only', '--diff-filter=AR'], { cwd: ROOT, encoding: 'utf8' });
+  const bad = out.split('\n').filter((f) => f && isBlocked(f));
+  return bad.length ? (fail(bad), 1) : 0;
+}
+
+function main(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return 0;
+  }
+  const input = payload.tool_input ?? {};
+  const bad = writesOf(payload, payload.cwd ?? ROOT).filter((w) => w.op !== 'delete' && isBlocked(w.path)).map((w) => w.path);
+  if (payload.tool_name === 'Bash' && !commandLeavesProject(input.command)) {
+    const tokens = (input.command ?? '').split(/\s+/).map((t) => t.replace(/^['"]|['"]$/g, ''));
+    if (/\b(curl|wget|convert|magick|sips|rsvg-convert|ffmpeg)\b/.test(input.command ?? '')) bad.push(...tokens.filter((t) => t && isBlocked(t, payload.cwd ?? ROOT)));
+  }
+  return bad.length ? fail([...new Set(bad)]) : 0;
+}
+
+function selftest() {
+  const me = fileURLToPath(import.meta.url);
+  const dir = scratchProject({}, { folders: { app: { path: 'lib/app/src', purpose: 'app' }, docs: { path: 'docs', purpose: 'docs' } }, concepts: {} });
+  const w = (file) => runHook(me, dir, writeOf(join(dir, file), 'x'));
+  return verdicts('no-shipped-images', [
+    ['an image in a code folder', w('lib/app/src/logo.png'), 2],
+    ['an image in src/', w('src/icon.svg'), 2],
+    ['an image in resources/', w('resources/knob.webp'), 2],
+    ['a font is data, not a picture', w('resources/Inter.ttf'), 0],
+    ['a golden render under tests/', w('tests/goldens/panel.png'), 0],
+    ['a picture in docs/', w('docs/shot.png'), 0],
+    ['cp of an image into a code folder', runHook(me, dir, bashOf('cp /tmp/a.png lib/app/src/a.png', dir)), 2],
+    ['cp into tests/', runHook(me, dir, bashOf('cp /tmp/a.png tests/goldens/a.png', dir)), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) {
+  const arg = process.argv.slice(2);
+  process.exit(arg.includes('--selftest') ? selftest() : arg.includes('--git-staged') ? gitStaged() : await asHook('no-shipped-images', main));
+}

package/packs/stellix/pack.json

@@ -0,0 +1,61 @@
+{
+  "name": "stellix",
+  "version": "1.0.0",
+  "description": "Stellix spec laws: the world, determinism, generated reset, no shipped images.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/stellix"
+  },
+  "keywords": [
+    "synth"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {
+    "world": {
+      "path": "src/world",
+      "purpose": "the world: coordinates, travellers, hits, pushes, the snapshot writer, the seeded generator, world maths"
+    },
+    "records": {
+      "path": "records",
+      "purpose": "layout and state records: every piece of state declared once with its starting value"
+    }
+  },
+  "concepts": {
+    "world": [
+      "world"
+    ],
+    "records": [
+      "records"
+    ],
+    "params": [
+      "records"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-shipped-images.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "files": {
+    "seeded_random": "src/world/seeded_random.h",
+    "world_math": "src/world/world_math.h",
+    "snapshot": "src/world/snapshot.h"
+  }
+}

package/packs/stellix/rules/stellix-deterministic-world.md

@@ -0,0 +1,29 @@
+---
+# concepts: world, audio, painter, ui, tests
+paths:
+  - "placeholder"
+---
+
+# Same playing from the same state gives the same sound and the same picture
+
+From spec §0 rule 4, §6.1, §6.3, §7.3.
+
+<constraints>
+Always do:
+- Work out every path, bounce, impact and shatter by formula from what was played, where it hits, and the world's settings.
+- Use the world's one seeded generator as the only randomness (RANDOM, opt-in, off in INIT and every factory patch). It may reach modulation and effects only, never pitch, wave, tone, level, filter type or a SOUND choice. Under FOLLOW THE SONG its seed restarts with the song position.
+- Run the world at a fixed 240 Hz tick, independent of buffer size and sample rate. Solve crossings and touches inside the tick and place each event at its exact sample.
+- Keep looking separate from sound: hovering, zooming and moving the camera never change the sound (unless FROM VIEW is on, where the camera becomes patch data).
+
+Never do:
+- Call any random source other than the seeded generator. `.claude/checks/one-seeded-random.json` blocks it.
+- Let the frame rate, the window being open, or the host buffer size change what is heard.
+- Let a control take keyboard focus. QWERTY always plays (`no-keyboard-focus.json`).
+</constraints>
+
+## Check
+Gates, each proven red by a planted fault:
+- **Bounce repeat:** the same MIDI from INIT renders bit-identical twice, at buffer sizes 64, 512 and 2048 and at 44.1, 48 and 96 kHz.
+- **View:** with FROM VIEW off, a camera move or a hover leaves the render bit-identical.
+- **Four tempos:** HITS and BEATS notes land on their exact samples.
+- **Settle:** after a hard passage the world comes to rest once playing stops.

package/packs/stellix/rules/stellix-reset-generated.md

@@ -0,0 +1,24 @@
+---
+# concepts: records, params, world
+paths:
+  - "placeholder"
+---
+
+# Reset is generated from the records, never written by hand
+
+From spec §0 rule 5.
+
+<constraints>
+Always do:
+- Declare every piece of patch state once in the records, with its starting value. The reset is generated from that list, and state without a starting value must not compile.
+- Treat a patch load as a reset followed by an apply, so nothing survives from the previous patch.
+- Make reset clear motion too: every mover, note in flight and shatter piece. Every held note gets its note-off.
+- Keep MAIN volume, octave, the wheel positions, LIMIT and SETTINGS outside the patch, as the patch law says.
+
+Never do:
+- Write a reset by hand, or add a field to a hand-made list.
+- Plant state in a member variable that isn't declared in the records.
+</constraints>
+
+## Check
+Reset gate: move every control and every piece of patch state away from its start, set the world moving with notes in flight, then reset. The render must be bit-identical to a fresh INIT. Plant the fault (one field outside the list) and the gate must show red.

package/packs/stellix/rules/stellix-world-snapshot.md

@@ -0,0 +1,27 @@
+---
+# concepts: world, painter, audio
+paths:
+  - "placeholder"
+---
+
+# The painter sees the world only through one plain-data snapshot
+
+From spec §8 and §7.3.
+
+<constraints>
+Always do:
+- Keep the world as coordinates on the audio side: a traveller is a position and a velocity; a moon is a position, a radius and a border; a planet is a position and a radius. Each 240 Hz tick moves travellers, checks distances and turns hits into pushes, as arithmetic only.
+- Publish one plain-data snapshot per tick (positions, pushes, hits) behind a single atomic index. Use double or triple buffering, whichever keeps the reader from ever seeing a half-written one.
+- Let the painter read only the snapshot, at its own frame rate. It may extrapolate between ticks with the same formulas, but when they differ the snapshot wins.
+- Compute predictions (ghost paths, "cutoff +12%") with the engine's own formula code on a copy of the world's state, never with a second version of the formulas.
+
+Never do:
+- Include anything from the painter, a GPU API or JUCE OpenGL in world, engine or voice code. `.claude/checks/world-never-includes-painter.json` blocks it.
+- Do camera, perspective, lighting, mesh, bloom or path drawing work inside the world tick. The look-only test's 17 ms demo step is the example of what this forbids.
+- Let the audio thread wait for, lock against or allocate for the painter.
+</constraints>
+
+## Check
+- Torn-snapshot gate: a reader hammering the snapshot while the world writes at full rate must never see a mixed one. Plant the fault by writing in place, and the gate goes red.
+- Prediction gate: play a passage; every predicted hit happens, and no unpredicted hit occurs.
+- The realtime-guard hook blocks GPU calls in audio-thread code.

package/packs/stellix/rules/world-continuous-collision.md

@@ -0,0 +1,26 @@
+---
+# concepts: world, tests
+paths:
+  - "placeholder"
+---
+
+# Every hit inside a tick is found exactly once and placed at its sample
+
+From spec 6.0 and 7.3: the tick never quantises time.
+
+<constraints>
+Always do:
+- Sweep each traveller across the tick. A formula curve is split into a fixed number K of substeps (fixed K keeps it deterministic), and each chord is swept against every sphere in reach.
+- Solve segment against sphere with the numerically stable quadratic: `q = −½(b + sign(b)·√disc)`, roots `c'/q` and `q/a` (Ericson, *Real-Time Collision Detection* §5.3). Take the smallest `t` in [0, 1).
+- Keep a contact state per traveller/planet pair. A hit fires on the *entering* transition only; a traveller starting inside counts once, at t = 0.
+- Use a skin tolerance relative to the radius, and settle simultaneous hits by pair ID.
+- Convert `t` to a sample with integer or fixed-point arithmetic: `tickStartSample + floor(t · samplesPerTick)`.
+
+Never do:
+- Test only the end position of a tick (fast travellers tunnel through small moons).
+- Let a resting contact fire again every tick.
+</constraints>
+
+## Check
+- Test: a traveller at 10x the fastest launch speed crosses a sphere of the smallest radius. Exactly one event, at the analytically expected sample, ±0.
+- Test: grazing paths (tangent, ±1 skin) give the same verdict on both platforms (part of the cross-platform event-log gate).

package/packs/stellix/rules/world-fp-determinism.md

@@ -0,0 +1,28 @@
+---
+# concepts: world, build
+paths:
+  - "placeholder"
+---
+
+# The world gives bit-identical results on Mac and Windows
+
+The world (travellers, hits, pushes, event samples) must replay identically on ARM64 and x86-64. Audio DSP only needs to be identical per platform.
+
+<constraints>
+Always do:
+- Build world sources with `-ffp-contract=off` (clang and clang-cl) and `/fp:precise` without `/fp:contract` (MSVC). Clang fuses multiply-adds by default (`-ffp-contract=on`), and Apple clang on ARM64 emits `fmadd`.
+- Use only `+ − × ÷ sqrt` in the world. IEEE-754 rounds those five exactly, so they match everywhere. Build `sin`, `cos`, `exp` and `pow` from the house polynomial versions (range reduction plus Horner) in one world-math file.
+- Keep world state in fixed arrays ordered by stable ID, and break sort ties by ID.
+- Keep time as integers: sample timestamps as `int64`, and the tick phase as an integer ratio (48 kHz/240 Hz is exactly 200 samples, but 44.1 kHz/240 Hz is 183.75, so accumulate the remainder exactly).
+- Design out denormals in the world: snap magnitudes below 1e-30 to zero explicitly rather than relying on CPU flush modes, which differ between ARM and x86.
+- Consider 64-bit fixed point (e.g. Q32.32) for positions. It removes compiler and flag risk entirely (house option, decided in the world plan).
+
+Never do:
+- Call libm (`std::sin`, `std::exp`, `std::pow`…) in world code. Apple libm, the MSVC UCRT and glibc differ in the last bits.
+- Use `std::unordered_*` or iterate anything in hash order in the world.
+- Use fast-math or FMA-contraction flags anywhere (`no-fast-math` check).
+</constraints>
+
+## Check
+- `.claude/checks/world-no-libm.json` and `world-no-unordered.json` block libm calls and unordered containers in world code.
+- Cross-platform gate: render N seconds from a saved state on both CI platforms. The world event log (event, sample index, payload hash) must be byte-identical between Mac and Windows; the audio hash must be identical between runs on each platform.

package/packs/stored-text/checks/no-raw-html-from-data.json

@@ -0,0 +1,31 @@
+{
+  "id": "no-raw-html-from-data",
+  "why": "HTML put on a page by hand skips the sanitize step: stored markdown can carry a script. The only HTML inserted raw is the renderer's output.",
+  "rule": ".claude/rules/stored-text-renders-once.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.mjs",
+    "**/*.vue",
+    "**/*.svelte",
+    "**/*.html"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/stored-text.*"
+  ],
+  "strings": true,
+  "pattern": "dangerouslySetInnerHTML=\\{\\{\\s*__html:(?!\\s*renderStored\\()|\\.(?:innerHTML|outerHTML)\\s*\\+?=(?!\\s*(?:renderStored\\(|['\"`]{2}))|\\bv-html=\"(?!renderStored\\()",
+  "bad": "<div dangerouslySetInnerHTML={{ __html: row.body }} />\n",
+  "good": "<StoredText source={row.body} />\n<div dangerouslySetInnerHTML={{ __html: renderStored(row.body) }} />\nel.innerHTML = '';\n"
+}