Skip to content

README.md

Latest commit

 

History

History
147 lines (101 loc) · 8.87 KB

README.md

File metadata and controls

147 lines (101 loc) · 8.87 KB

Polychron

Generative polyrhythmic composition engine. Two independent rhythmic layers interact through 64 cross-layer modules, governed by 27 trust-scored systems and 18 self-calibrating hypermeta controllers. Produces MIDI compositions with emergent musical behaviors arising from cross-system interaction.

7 feedback loops · 19 stutter variants · 12 CIM coordination dials · 27 ESLint rules

Two-Mode Codebase

Development happens in two interleaving spaces, treated as synergistic-but-distinct partners:

  • Composition (src/) — the engine described below. Mode-specific judgment-call rules: doc/SRC.md.
  • HME (tools/HME/) — the cognitive scaffolding around it: proxy middleware that intercepts every Anthropic API call, stop-chain behavioral detectors, a vector-indexed KB, an autonomous evolution loop, and the i/<tool> shell wrapper surface. Tool reference and workflow: doc/HME.md.

CLAUDE.md holds universal hard rules and working style. Mechanical rules (lint, validators, hooks, jurisdiction checks) are auto-enforced by the toolchain — not documented as text.

Quick Start

npm install
npm run main   # lint, typecheck, compose, analyze metrics
npm run render # MIDI -> WAV via FluidSynth + FFmpeg

Prerequisites: Node.js 20+, Python 3, FluidSynth, FFmpeg, SF2 soundfont at ~/Downloads/SGM-v2.01-NicePianosGuitarsBass-V1.2.sf2

Lab experiments:

node lab/run.js                    # run all sketches
node lab/run.js sketch-name        # run specific sketch

Architecture Overview

The system has three interacting layers:

Conductor -- unified signal pipeline computing density, tension, and flicker products every beat. 37 registered recorders advance state. 18 hypermeta controllers self-calibrate coupling targets, thresholds, and gains. Tick L1-only to prevent polyrhythmic double-counting.

Cross-Layer -- 45 registered modules managing inter-layer dynamics: rhythmic complement (hocket/antiphony/canon), spectral gap-filling, velocity interference, articulation contrast, convergence detection, stutter contagion, and the Coordination Independence Manager (CIM) with 12 module-pair dials.

Play Loop -- alternates L1/L2 via LM.activate() with full per-layer state isolation (crossModulation, balance, flipBin). Each beat: conductor tick -> processBeat -> playNotes -> crossLayerBeatRecord -> trust/feedback updates.

Signal flow: doc/ARCHITECTURE.md

Subsystems

  • src/utils/ — core utilities, registries, random, validation
  • src/conductor/ — signal pipeline, profiles, dynamics, coupling, meta
  • src/rhythm/ — pattern generation, feedback listeners, drums
  • src/time/ — LayerManager, tempo feel, timing
  • src/composers/ — 11 composer types, voice management, motif
  • src/fx/ — stutter (19 variants), binaural, balance, noise
  • src/crossLayer/ — dynamics, harmony, rhythm, structure, trust, CIM
  • src/writer/ — CSV output, grandFinale
  • src/play/ — beat loop, emission, layer passes

Details: doc/SUBSYSTEMS.md

Key Systems

Stutter Variant Ecosystem

19 note stutter variants selected per-beat by 12 weighted signal dimensions (regime, phase, articulation, harmonic distance, coupling labels, entropy reversal, call-response, phrase boundary, hocket mode, self-balancing frequency). Euclidean pattern gating (75%) + sustain-proportional probabilistic gate.

Details: doc/STUTTER_SYSTEM.md

Coordination Independence Manager (CIM)

12 module-pair dials (0=independent, 1=coordinated) dynamically driven by regime, phase, topology, intent curves, and entropy. Phase-gated operation, chaos mode, oscillation mode. Controls rest synchronization, stutter contagion, spectral complementarity, phase lock, velocity interference, and more.

Details: doc/COORDINATION_INDEPENDENCE.md

Hypermeta Self-Calibrating Controllers

18 controllers auto-tune coupling targets, regime distribution, pipeline centroids, flicker range, trust starvation, gain budgets, phase floors, pair ceilings, warmup ramps, and correlation shuffling. Health-gated evolution scaling. Structural discontinuity detection with fast reconvergence.

Details: doc/HYPERMETA.md

Trust Ecology

27 trust-scored cross-layer systems compete for influence via EMA-weighted payoffs. Trust dominance biases composer family selection and instrument palette. Starvation auto-nourishment prevents permanent module death. Trust velocity tracking with hysteresis.

Details: doc/TRUST_ECOLOGY.md

Feedback Loops

7 registered closed-loop feedback controllers with resonance dampening. Correlation shuffler detects pathological correlations (reinforcement spirals, tug-of-war, stasis) and applies graduated perturbations. FeedbackOscillator creates multi-round-trip cross-layer energy loops with pitch class memory.

Details: doc/FEEDBACK_LOOPS.md

Adaptive Infrastructure

Cross-run warm-start via output/metrics/adaptive-state.json. Reconvergence accelerator detects structural discontinuities and spikes EMA alphas. Regime-adaptive alphas (3x on transition, decay 0.88/tick). Effectiveness-weighted convergence rates (proven controllers adapt faster).

Details: doc/ADAPTIVE_INFRASTRUCTURE.md

Convergence Systems

Cross-layer onset convergence detection, harmonic burst triggers, velocity surges, memory histogram (learned rhythmic accent patterns), and convergence cascades (multi-system impact chains).

Details: doc/CONVERGENCE_SYSTEMS.md

Layer Isolation

Two polyrhythmic layers (L1/L2) alternate via LM.activate(). Critical per-layer state: crossModulation, balance values, flipBin, stutter EMAs, emission metrics, journey boldness, arc types. Conductor recorders tick L1-only via registry gate. Per-layer flipBin prevents binaural detune desync.

Details: doc/ARCHITECTURE.md (Layer Isolation section)

Conductor Profiles

  • atmospheric — dense, lush, high reverb/delay; canon-biased rhythm; oscillating threshold 0.14
  • explosive — maximum energy, wide dynamics, aggressive stutter rates
  • restrained — conservative density (0.25-0.42), low emission gates
  • minimal — very sparse, near-silent, high stutter emission for texture
  • default — balanced baseline
  • rhythmicDrive — rhythm-forward, high subdivision counts

Diagnostics

Generated per-run in output/metrics/:

  • trace-summary.json — beats, regimes, signals, coupling, trust, axis energy
  • golden-fingerprint.json — 10-dimension stability fingerprint
  • fingerprint-comparison.json — run-over-run delta with STABLE/EVOLVED/DRIFTED verdict
  • narrative-digest.md — prose composition story
  • runtime-snapshots.json — CIM dials, stutter variant counts, shuffler state
  • adaptive-state.json — cross-run warm-start EMAs
  • feedback_graph.json — 7 feedback loop topology
  • conductor-map.md — conductor intelligence map
  • crosslayer-map.md — cross-layer topology

Documentation

Dependencies

  • @tonaljs/rhythm-pattern -- Euclidean/binary/hex pattern generation
  • Node.js built-ins only (no bundler, no transpiler)
  • FluidSynth + FFmpeg for audio rendering (not required for composition)