flux-tensor-midi 0.1.0__tar.gz

flux_tensor_midi-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: flux-tensor-midi
+Version: 0.1.0
+Summary: PLATO rooms as musicians — flux tensor MIDI ensemble coordination
+Author-email: Forgemaster <forgemaster@superinstance.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/flux-tensor-midi
+Project-URL: Documentation, https://github.com/SuperInstance/flux-tensor-midi#readme
+Project-URL: Repository, https://github.com/SuperInstance/flux-tensor-midi
+Project-URL: Issues, https://github.com/SuperInstance/flux-tensor-midi/issues
+Keywords: midi,flux,tensor,plato,ensemble,music
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# FLUX-Tensor-MIDI ⚒️
+
+**PLATO rooms as musicians.** Each room has a T-0 clock, produces timestamped events (tiles=notes), listens to other rooms, snaps to rhythm via Eisenstein lattice, and sends side-channels (nods/smiles/frowns) for ensemble coordination.
+
+Zero external dependencies. Pure Python 3.10+.
+
+## Musical Analogy Table
+
+| PLATO Concept        | Musical Equivalent    | MIDI Mapping              |
+|----------------------|-----------------------|---------------------------|
+| Room                 | Musician              | MIDI Channel              |
+| T-0 Clock            | Metronome / Conductor | MIDI Clock (0xF8)         |
+| Tile (event)         | Note                  | Note On/Off               |
+| FluxVector (9-ch)    | Chord / Harmonic Spectrum | 9 MIDI notes (C4–D5) |
+| Salience             | Note Velocity         | Velocity (0–127)          |
+| Tolerance            | Pitch Bend / Jitter   | Pitch Bend range          |
+| Eisenstein Snap      | Rhythmic Quantization | Grid snapping             |
+| Nod                  | Nod (agreement)       | CC #1 (Mod Wheel)         |
+| Smile                | Smile (approval)      | CC #2 (Breath)            |
+| Frown                | Frown (disagreement)  | CC #3 (Expression)        |
+| Listening (room→room)| Musician's ear        | MIDI Channel routing      |
+| Conductor            | Band leader / click   | Master MIDI Clock          |
+| Ensemble             | Band / Orchestra      | Multi-channel MIDI output |
+| Jaccard Harmony      | Chord similarity      | Chromatic interval match  |
+| Rhythmic Role        | Groove part           | Program change (patch)    |
+
+## Rhythm Ratios (Eisenstein Lattice)
+
+| Role        | Ratio | Period (at 120 BPM) | Musical Feel       |
+|-------------|-------|---------------------|--------------------|
+| Root        | 1:1   | 500 ms              | Downbeat / quarter |
+| Halftime    | 2:1   | 1000 ms             | Half speed         |
+| Triplet     | 3:2   | 750 ms              | Swung feel         |
+| Waltz       | 3:1   | 1500 ms             | Waltz time         |
+| Compound    | 4:3   | ~667 ms             | Compound meter     |
+| Doubletime  | 1:2   | 250 ms              | Double speed       |
+| Offset      | 1:1   | 500 ms + 120° phase | Syncopated         |
+| Quintuple   | 5:4   | 625 ms              | Quintuple meter    |
+| Septuple    | 7:4   | 875 ms              | Septuple meter     |
+
+Covering radius: **1/√3 ≈ 0.577** — optimal hexagonal tiling.
+
+## Quick Start
+
+```bash
+pip install flux-tensor-midi
+```
+
+```python
+from flux_tensor_midi import FluxVector, TZeroClock, RoomMusician, EisensteinSnap
+from flux_tensor_midi.core.snap import RhythmicRole
+from flux_tensor_midi.ensemble.band import Band
+
+# Create musicians with different rhythmic roles
+piano = RoomMusician("Piano", role=RhythmicRole.ROOT)
+bass = RoomMusician("Bass", role=RhythmicRole.HALFTIME)
+drums = RoomMusician("Drums", role=RhythmicRole.TRIPLET)
+
+# Form a band with a conductor
+band = Band("Trio", conductor=piano, bpm=120.0)
+band.add_musician(bass)
+band.add_musician(drums)
+band.everyone_listens_to_everyone()
+
+# Set some initial state
+piano.update_state(FluxVector([0.8, 0.0, 0.6, 0.0, 0.7, 0.0, 0.0, 0.0, 0.0]))
+bass.update_state(FluxVector([0.0, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))  # simple root
+
+# Tick the band
+results = band.tick_all()
+print(f"Piano event at {results['Piano'][0]:.1f}ms")
+
+# Check harmony
+hs = band.harmony()
+print(f"Chord quality: {hs.quality()}, consonance: {hs.consonance():.3f}")
+
+# Side-channel comms
+piano.send_nod(bass)
+print(f"Bass received nods from: {bass.receive_sidechannels()['nods']}")
+```
+
+## Package Structure
+
+```
+flux_tensor_midi/
+├── __init__.py
+├── core/
+│   ├── __init__.py
+│   ├── flux.py       — FluxVector (9-ch tensor with salience+tolerance)
+│   ├── clock.py      — TZeroClock (EWMA-adaptive metronome)
+│   ├── room.py       — RoomMusician (PLATO room as musician)
+│   └── snap.py       — EisensteinSnap (rhythmic quantization lattice)
+├── midi/
+│   ├── __init__.py
+│   ├── events.py     — MidiEvent, NoteName, flux→MIDI conversion
+│   ├── clock.py      — MidiClock (24 PPQN, software clock)
+│   └── channel.py    — MidiChannel mapping by rhythmic role
+├── sidechannel/
+│   ├── __init__.py
+│   ├── nod.py        — Nod gesture (agreement/acknowledgment)
+│   ├── smile.py      — Smile gesture (positive affect)
+│   └── frown.py      — Frown gesture (disagreement/concern)
+├── harmony/
+│   ├── __init__.py
+│   ├── jaccard.py    — Jaccard similarity for FluxVector sets
+│   ├── spectrum.py   — Spectral analysis (centroid, flux, autocorr)
+│   └── chord.py      — HarmonyState (consonance, quality, voice leading)
+└── ensemble/
+    ├── __init__.py
+    ├── band.py       — Band (ensemble with conductor)
+    └── score.py      — Score (recorded performance, export)
+```
+
+## Running Tests
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT

flux_tensor_midi-0.1.0/README.md

@@ -0,0 +1,124 @@
+# FLUX-Tensor-MIDI ⚒️
+
+**PLATO rooms as musicians.** Each room has a T-0 clock, produces timestamped events (tiles=notes), listens to other rooms, snaps to rhythm via Eisenstein lattice, and sends side-channels (nods/smiles/frowns) for ensemble coordination.
+
+Zero external dependencies. Pure Python 3.10+.
+
+## Musical Analogy Table
+
+| PLATO Concept        | Musical Equivalent    | MIDI Mapping              |
+|----------------------|-----------------------|---------------------------|
+| Room                 | Musician              | MIDI Channel              |
+| T-0 Clock            | Metronome / Conductor | MIDI Clock (0xF8)         |
+| Tile (event)         | Note                  | Note On/Off               |
+| FluxVector (9-ch)    | Chord / Harmonic Spectrum | 9 MIDI notes (C4–D5) |
+| Salience             | Note Velocity         | Velocity (0–127)          |
+| Tolerance            | Pitch Bend / Jitter   | Pitch Bend range          |
+| Eisenstein Snap      | Rhythmic Quantization | Grid snapping             |
+| Nod                  | Nod (agreement)       | CC #1 (Mod Wheel)         |
+| Smile                | Smile (approval)      | CC #2 (Breath)            |
+| Frown                | Frown (disagreement)  | CC #3 (Expression)        |
+| Listening (room→room)| Musician's ear        | MIDI Channel routing      |
+| Conductor            | Band leader / click   | Master MIDI Clock          |
+| Ensemble             | Band / Orchestra      | Multi-channel MIDI output |
+| Jaccard Harmony      | Chord similarity      | Chromatic interval match  |
+| Rhythmic Role        | Groove part           | Program change (patch)    |
+
+## Rhythm Ratios (Eisenstein Lattice)
+
+| Role        | Ratio | Period (at 120 BPM) | Musical Feel       |
+|-------------|-------|---------------------|--------------------|
+| Root        | 1:1   | 500 ms              | Downbeat / quarter |
+| Halftime    | 2:1   | 1000 ms             | Half speed         |
+| Triplet     | 3:2   | 750 ms              | Swung feel         |
+| Waltz       | 3:1   | 1500 ms             | Waltz time         |
+| Compound    | 4:3   | ~667 ms             | Compound meter     |
+| Doubletime  | 1:2   | 250 ms              | Double speed       |
+| Offset      | 1:1   | 500 ms + 120° phase | Syncopated         |
+| Quintuple   | 5:4   | 625 ms              | Quintuple meter    |
+| Septuple    | 7:4   | 875 ms              | Septuple meter     |
+
+Covering radius: **1/√3 ≈ 0.577** — optimal hexagonal tiling.
+
+## Quick Start
+
+```bash
+pip install flux-tensor-midi
+```
+
+```python
+from flux_tensor_midi import FluxVector, TZeroClock, RoomMusician, EisensteinSnap
+from flux_tensor_midi.core.snap import RhythmicRole
+from flux_tensor_midi.ensemble.band import Band
+
+# Create musicians with different rhythmic roles
+piano = RoomMusician("Piano", role=RhythmicRole.ROOT)
+bass = RoomMusician("Bass", role=RhythmicRole.HALFTIME)
+drums = RoomMusician("Drums", role=RhythmicRole.TRIPLET)
+
+# Form a band with a conductor
+band = Band("Trio", conductor=piano, bpm=120.0)
+band.add_musician(bass)
+band.add_musician(drums)
+band.everyone_listens_to_everyone()
+
+# Set some initial state
+piano.update_state(FluxVector([0.8, 0.0, 0.6, 0.0, 0.7, 0.0, 0.0, 0.0, 0.0]))
+bass.update_state(FluxVector([0.0, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))  # simple root
+
+# Tick the band
+results = band.tick_all()
+print(f"Piano event at {results['Piano'][0]:.1f}ms")
+
+# Check harmony
+hs = band.harmony()
+print(f"Chord quality: {hs.quality()}, consonance: {hs.consonance():.3f}")
+
+# Side-channel comms
+piano.send_nod(bass)
+print(f"Bass received nods from: {bass.receive_sidechannels()['nods']}")
+```
+
+## Package Structure
+
+```
+flux_tensor_midi/
+├── __init__.py
+├── core/
+│   ├── __init__.py
+│   ├── flux.py       — FluxVector (9-ch tensor with salience+tolerance)
+│   ├── clock.py      — TZeroClock (EWMA-adaptive metronome)
+│   ├── room.py       — RoomMusician (PLATO room as musician)
+│   └── snap.py       — EisensteinSnap (rhythmic quantization lattice)
+├── midi/
+│   ├── __init__.py
+│   ├── events.py     — MidiEvent, NoteName, flux→MIDI conversion
+│   ├── clock.py      — MidiClock (24 PPQN, software clock)
+│   └── channel.py    — MidiChannel mapping by rhythmic role
+├── sidechannel/
+│   ├── __init__.py
+│   ├── nod.py        — Nod gesture (agreement/acknowledgment)
+│   ├── smile.py      — Smile gesture (positive affect)
+│   └── frown.py      — Frown gesture (disagreement/concern)
+├── harmony/
+│   ├── __init__.py
+│   ├── jaccard.py    — Jaccard similarity for FluxVector sets
+│   ├── spectrum.py   — Spectral analysis (centroid, flux, autocorr)
+│   └── chord.py      — HarmonyState (consonance, quality, voice leading)
+└── ensemble/
+    ├── __init__.py
+    ├── band.py       — Band (ensemble with conductor)
+    └── score.py      — Score (recorded performance, export)
+```
+
+## Running Tests
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT

flux_tensor_midi-0.1.0/flux_tensor_midi/__init__.py

@@ -0,0 +1,21 @@
+"""
+FLUX-Tensor-MIDI: PLATO rooms as musicians.
+
+Each room has a T-0 clock, produces timestamped events (tiles=notes),
+listens to others, snaps to rhythm via Eisenstein lattice, and sends
+side-channels (nods/smiles/frowns) for ensemble coordination.
+
+Zero external dependencies. Pure Python 3.10+.
+"""
+
+from flux_tensor_midi.core.flux import FluxVector
+from flux_tensor_midi.core.clock import TZeroClock
+from flux_tensor_midi.core.room import RoomMusician
+from flux_tensor_midi.core.snap import EisensteinSnap
+
+__all__ = [
+    "FluxVector",
+    "TZeroClock",
+    "RoomMusician",
+    "EisensteinSnap",
+]

flux_tensor_midi-0.1.0/flux_tensor_midi/core/__init__.py

@@ -0,0 +1,27 @@
+"""
+Core modules for FLUX-Tensor-MIDI.
+"""
+
+from flux_tensor_midi.core.flux import FluxVector
+from flux_tensor_midi.core.clock import TZeroClock
+from flux_tensor_midi.core.room import RoomMusician
+from flux_tensor_midi.core.snap import (
+    EisensteinSnap,
+    EisensteinRatio,
+    RhythmicRole,
+    UNISON,
+    HALFTIME,
+    TRIPLET,
+)
+
+__all__ = [
+    "FluxVector",
+    "TZeroClock",
+    "RoomMusician",
+    "EisensteinSnap",
+    "EisensteinRatio",
+    "RhythmicRole",
+    "UNISON",
+    "HALFTIME",
+    "TRIPLET",
+]

flux_tensor_midi-0.1.0/flux_tensor_midi/core/clock.py

@@ -0,0 +1,144 @@
+"""
+TZeroClock: An EWMA-adaptive clock for PLATO room T-0 time.
+
+Each RoomMusician has a TZeroClock that produces drift-corrected
+timestamps.  Uses Exponentially Weighted Moving Average to adapt
+to observed clock skew from the conductor (or any reference beat).
+"""
+
+from __future__ import annotations
+import math
+import time
+from typing import Callable
+
+
+class TZeroClock:
+    """An adaptive clock using EWMA for drift correction.
+
+    Parameters
+    ----------
+    alpha : float, default=0.125
+        EWMA smoothing factor.  Higher = faster adapt, lower = smoother.
+    reference_clock : Callable[[], float], optional
+        Source of wall time in seconds.  Defaults to time.monotonic.
+    initial_ticks : int, default=0
+        Starting tick count.
+    bpm : float, default=120.0
+        Beats per minute for tick duration.
+    """
+
+    def __init__(
+        self,
+        alpha: float = 0.125,
+        reference_clock: Callable[[], float] | None = None,
+        initial_ticks: int = 0,
+        bpm: float = 120.0,
+    ):
+        if not 0 < alpha < 1:
+            raise ValueError(f"alpha must be in (0, 1), got {alpha}")
+        if bpm <= 0:
+            raise ValueError(f"bpm must be positive, got {bpm}")
+
+        self._alpha = alpha
+        self._clock = reference_clock or time.monotonic
+        self._ticks = initial_ticks
+        self._bpm = bpm
+
+        # EWMA state
+        self._drift: float = 0.0  # ms drift estimate
+        self._last_wall: float = self._clock()  # last wall clock reading
+
+        # Timing
+        self._tick_duration_s: float = 60.0 / bpm  # seconds per tick
+        self._start_wall: float = self._last_wall
+        self._start_tick: float = 0.0  # virtual tick time at start
+
+    @property
+    def alpha(self) -> float:
+        return self._alpha
+
+    @property
+    def bpm(self) -> float:
+        return self._bpm
+
+    @property
+    def tick_duration_ms(self) -> float:
+        return self._tick_duration_s * 1000.0
+
+    @property
+    def ticks(self) -> int:
+        return self._ticks
+
+    # ---- core operations ----
+
+    def tick(self) -> float:
+        """Advance one tick and return the corrected timestamp (ms)."""
+        now = self._clock()
+        expected_s = (self._ticks + 1) * self._tick_duration_s
+        actual_s = now - self._start_wall
+
+        # Observed drift in ms
+        observed_drift_ms = (actual_s - expected_s) * 1000.0
+
+        # EWMA update
+        self._drift = self._alpha * observed_drift_ms + (1 - self._alpha) * self._drift
+
+        # Corrected timestamp (ms): expected time - estimated drift
+        corrected_ms = expected_s * 1000.0 - self._drift
+
+        self._ticks += 1
+        self._last_wall = now
+        return corrected_ms
+
+    def time_ms(self) -> float:
+        """Current corrected time in ms (without advancing ticks)."""
+        now = self._clock()
+        elapsed_s = now - self._start_wall
+        return elapsed_s * 1000.0 - self._drift
+
+    def drift_ms(self) -> float:
+        """Current estimated drift in ms (negative = ahead of wall)."""
+        return self._drift
+
+    def reset(self, bpm: float | None = None) -> None:
+        """Reset the clock.  Optionally set a new BPM."""
+        if bpm is not None:
+            if bpm <= 0:
+                raise ValueError(f"bpm must be positive, got {bpm}")
+            self._bpm = bpm
+            self._tick_duration_s = 60.0 / bpm
+        self._drift = 0.0
+        self._ticks = 0
+        self._last_wall = self._clock()
+        self._start_wall = self._last_wall
+        self._start_tick = 0.0
+
+    def set_bpm(self, bpm: float) -> None:
+        """Change BPM mid-stream (preserves drift estimate)."""
+        if bpm <= 0:
+            raise ValueError(f"bpm must be positive, got {bpm}")
+        self._bpm = bpm
+        self._tick_duration_s = 60.0 / bpm
+
+    def synchronize_to(self, other: TZeroClock) -> None:
+        """Synchronize drift estimate to another clock."""
+        self._drift = other._drift
+
+    # ---- alignment ----
+
+    def align(self, reference_timestamp: float) -> float:
+        """Align clock to a reference timestamp, return correction applied."""
+        current = self.time_ms()
+        correction = reference_timestamp - current
+        # Apply correction by adjusting start wall equivalently
+        # (negative correction = we were ahead, move start_wall forward)
+        self._start_wall -= correction / 1000.0
+        return correction
+
+    @classmethod
+    def from_beat(cls, beat_number: int, bpm: float = 120.0, alpha: float = 0.125) -> TZeroClock:
+        """Create a clock pre-advanced to a specific beat."""
+        c = cls(alpha=alpha, bpm=bpm)
+        for _ in range(beat_number):
+            c.tick()
+        return c

flux_tensor_midi-0.1.0/flux_tensor_midi/core/flux.py

@@ -0,0 +1,192 @@
+"""
+FluxVector: A 9-channel tensor representing PLATO room state.
+
+Each channel has a salience (importance) and tolerance (jitter allowed).
+Inspired by the musical metaphor: 9 channels = notes in a harmonic spectrum,
+salience = velocity, tolerance = pitch bend range.
+"""
+
+from __future__ import annotations
+import math
+from typing import Sequence
+
+
+class FluxVector:
+    """A 9-channel vector with per-channel salience and tolerance.
+
+    PLATO rooms produce timestamped events.  Each event is encoded as a
+    FluxVector whose channels represent aspects of the room's state.
+    Salience is the strength (0–1), tolerance is the allowed jitter (ms).
+
+    Properties
+    ----------
+    channels : int
+        Fixed at 9.
+    salience : tuple[float, ...]
+        Length-9 tuple of salience values (0 ≤ s ≤ 1).
+    tolerance : tuple[float, ...]
+        Length-9 tuple of tolerance values in milliseconds.
+    """
+
+    _CHANNELS = 9
+
+    def __init__(
+        self,
+        values: Sequence[float],
+        salience: Sequence[float] | None = None,
+        tolerance: Sequence[float] | None = None,
+    ):
+        if len(values) != self._CHANNELS:
+            raise ValueError(f"FluxVector requires {self._CHANNELS} values, got {len(values)}")
+        if salience is not None and len(salience) != self._CHANNELS:
+            raise ValueError(f"salience must have {self._CHANNELS} elements, got {len(salience)}")
+        if tolerance is not None and len(tolerance) != self._CHANNELS:
+            raise ValueError(f"tolerance must have {self._CHANNELS} elements, got {len(tolerance)}")
+
+        self._values = tuple(float(v) for v in values)
+        self._salience = tuple(
+            float(s) if s is not None else 1.0 for s in (salience or [1.0] * self._CHANNELS)
+        )
+        self._tolerance = tuple(
+            float(t) if t is not None else 0.0 for t in (tolerance or [0.0] * self._CHANNELS)
+        )
+
+        # Clamp salience
+        self._salience = tuple(max(0.0, min(1.0, s)) for s in self._salience)
+
+    # ---- accessors ----
+
+    @property
+    def values(self) -> tuple[float, ...]:
+        return self._values
+
+    @property
+    def salience(self) -> tuple[float, ...]:
+        return self._salience
+
+    @property
+    def tolerance(self) -> tuple[float, ...]:
+        return self._tolerance
+
+    def __getitem__(self, idx: int) -> float:
+        return self._values[idx]
+
+    def __len__(self) -> int:
+        return self._CHANNELS
+
+    def __repr__(self) -> str:
+        return (
+            f"FluxVector({list(self._values)}, "
+            f"salience={list(self._salience)}, "
+            f"tolerance={list(self._tolerance)})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, FluxVector):
+            return NotImplemented
+        return (
+            self._values == other._values
+            and self._salience == other._salience
+            and self._tolerance == other._tolerance
+        )
+
+    def __hash__(self) -> int:
+        return hash((self._values, self._salience, self._tolerance))
+
+    # ---- operators ----
+
+    def __add__(self, other: FluxVector) -> FluxVector:
+        """Element-wise addition, weighting by minimum salience."""
+        if not isinstance(other, FluxVector):
+            return NotImplemented
+        w = tuple(min(a, b) for a, b in zip(self._salience, other._salience))
+        v = tuple(self._values[i] + other._values[i] for i in range(self._CHANNELS))
+        s = tuple(max(a, b) for a, b in zip(self._salience, other._salience))
+        t = tuple(max(a, b) for a, b in zip(self._tolerance, other._tolerance))
+        return FluxVector(v, salience=s, tolerance=t)
+
+    def __sub__(self, other: FluxVector) -> FluxVector:
+        """Element-wise subtraction, weighting by minimum salience."""
+        if not isinstance(other, FluxVector):
+            return NotImplemented
+        v = tuple(self._values[i] - other._values[i] for i in range(self._CHANNELS))
+        s = tuple(max(a, b) for a, b in zip(self._salience, other._salience))
+        t = tuple(max(a, b) for a, b in zip(self._tolerance, other._tolerance))
+        return FluxVector(v, salience=s, tolerance=t)
+
+    def __mul__(self, scalar: float) -> FluxVector:
+        """Scale all values by a scalar."""
+        v = tuple(x * scalar for x in self._values)
+        return FluxVector(v, salience=self._salience, tolerance=self._tolerance)
+
+    def __rmul__(self, scalar: float) -> FluxVector:
+        return self.__mul__(scalar)
+
+    # ---- norms / distance ----
+
+    @property
+    def magnitude(self) -> float:
+        """Euclidean norm."""
+        return math.sqrt(sum(x * x for x in self._values))
+
+    @property
+    def salience_weighted_magnitude(self) -> float:
+        """Euclidean norm weighted by salience."""
+        return math.sqrt(
+            sum(self._salience[i] * self._values[i] * self._values[i] for i in range(self._CHANNELS))
+        )
+
+    def distance_to(self, other: FluxVector, weighted: bool = False) -> float:
+        """Euclidean distance to another FluxVector.
+
+        If weighted, use salience-weighted difference.
+        """
+        if not isinstance(other, FluxVector):
+            raise TypeError("distance_to requires a FluxVector")
+        if weighted:
+            diff = tuple(
+                self._salience[i] * (self._values[i] - other._values[i])
+                for i in range(self._CHANNELS)
+            )
+        else:
+            diff = tuple(self._values[i] - other._values[i] for i in range(self._CHANNELS))
+        return math.sqrt(sum(d * d for d in diff))
+
+    def dot(self, other: FluxVector) -> float:
+        """Dot product, unweighted."""
+        if not isinstance(other, FluxVector):
+            raise TypeError("dot requires a FluxVector")
+        return sum(self._values[i] * other._values[i] for i in range(self._CHANNELS))
+
+    def cosine_similarity(self, other: FluxVector) -> float:
+        """Cosine similarity (-1 to 1)."""
+        mag_self = self.magnitude
+        mag_other = other.magnitude
+        if mag_self == 0.0 or mag_other == 0.0:
+            return 0.0
+        return self.dot(other) / (mag_self * mag_other)
+
+    # ---- tolerance helpers ----
+
+    def within_tolerance(self, other: FluxVector) -> bool:
+        """True if every channel is within its tolerance of the other."""
+        for i in range(self._CHANNELS):
+            if abs(self._values[i] - other._values[i]) > self._tolerance[i]:
+                return False
+        return True
+
+    def jitter(self, channel: int) -> float:
+        """Return the allowed jitter (tolerance) for a specific channel."""
+        return self._tolerance[channel]
+
+    @classmethod
+    def zero(cls, salience: Sequence[float] | None = None) -> FluxVector:
+        """Create a zero FluxVector with optional salience."""
+        return cls([0.0] * cls._CHANNELS, salience=salience)
+
+    @classmethod
+    def unit(cls, channel: int, salience: Sequence[float] | None = None) -> FluxVector:
+        """Create a unit vector along one channel."""
+        v = [0.0] * cls._CHANNELS
+        v[channel] = 1.0
+        return cls(v, salience=salience)