@wenathlan/debonair 2.0.136 → 2.0.138

package/docs/planning.pipeline.md

@@ -0,0 +1,198 @@
+# planning.pipeline — the 120+ step ladder of the full music pipeline
+
+> the wave the owner ordered: ingest a real track → the engine decomposes it
+> into the parametrized vector document → the document lands in the db with
+> the owner id and the big pointers → the references power the pattern miner
+> per genre → the composer generates a similar vector json → the engine
+> renders real audio → the take plays, publishes and shows in the vitrine.
+> every heavy stage runs SERVER SIDE (the gateway jobs, the saddle AVM
+> modalities) — the visitor's browser, cpu and gpu never run the pipeline.
+> companion of docs/planning.ladder.md (the kathesis verification ladder)
+> and docs/planning.v2.28-completo.md.
+>
+> ## the code synthesis of outros.debonair (the reference verdict)
+>
+> the full code read of the reference folder closed the method question —
+> the parts that PROVED real sound, the parts the composer mines:
+> - `v2/src/lib/audio/engine.ts` — the voice recipes to reimplement root
+>   side: kick pitch env 165→52→40 hz with the noise click, snare noise
+>   bandpass 1750 + dual triangle body, hat hp 7800, clap 4 bursts 9.5ms
+>   apart, 808 bass pitch snap hz*2→hz in 45ms through a drive shaper,
+>   supersaw lead, pad lp with the 0.28hz lfo, keys tremolo, master chain
+>   tanh waveshaper k=3.2 → compressor −13/18/4.5 → analyser, feedback
+>   delay 0.27s fb 0.34, reverb noise impulse tail pow(1−i/len, 2.2), the
+>   140ms look-ahead transport and the OfflineAudioContext render mirror →
+>   wav 16-bit / mp3 lamejs — the render proof the composer rides.
+> - `v2/src/lib/audio/generator.ts` — the composition brain: 48 scales, 9
+>   style presets with exact drum lanes (trap kick [0,6,10] snare [4,12]
+>   hat 16th lanes clap [4,12] swing 0.12; drill, lofi, house...), bass
+>   locked to kick, markov 1st-order melodies with the ±3 semitone bias,
+>   DRIFT_CYCLE and ENERGY_CYCLE build/drop, seeded prng (same prompt same
+>   take), vary() diatonic drift.
+> - `v2/src/app/api/analyze + similar + trainOnProject` — the pattern
+>   miner shape: note bigrams, 16-step drum histograms (adopt steps above
+>   0.55 after trainedOn ≥ 3), embedding centroid, bpm histogram, cosine
+>   similarity over the 32-dim embedding — the exact miner PV3
+>   reimplements over our ingest documents.
+> - `v1/v1 page.tsx` — the 6-layer biquad separation, the pcm store by
+>   session:second:track and the priority playback ladder (stored pcm →
+>   hex inline → seed synth → pattern synth) with the AudioBufferSource
+>   scheduling and the 1.0s per-second grid.
+> - `mjs/analyser.mjs + ffmpeg.mjs` — the node decode lane (ffmpeg f32le
+>   → stft → per_second vectors) with the known bpm bugs (no octave fold
+>   guard) our analyze already handles.
+> - the FAKE parts the new code never repeats: the ~200 decorative
+>   *Id/*Hash fields per second (constants and xor cosmetics), the
+>   expandFromSeed checksum claim (the checksum never validates — synthesis
+>   cannot reproduce pcm), the hex semantic signatures (0xKICK_SUB_HEAVY),
+>   the empty prisma/db/mini-services scaffolds, the yamnet removal.
+> - the honest separation limit the reference states: elements sharing the
+>   spectral range AND the pan position are mathematically inseparable
+>   without a trained model — the hpss pair (harmonic/percussive) is the
+>   proven floor, the vocal/bass/drum lanes ride the band filters on top.
+
+## wave PV0 — what already stands (verified, committed)
+
+- [x] PV0.001 hpss real separation with centered framing, ifft conj law and
+      f64 ola — conservation 2.3e-7 over the whole signal (hpss.ts)
+- [x] PV0.002 the ingest document debonair.ingest/1: mix + harmonic/percussive
+      stems, one vector frame per second (centroid, flatness, chroma, bands,
+      zcr, rms, beat, onsets) and the fnv-1a pcm hash (ingest.ts)
+- [x] PV0.003 the ingest store: gateway https with the house host law and the
+      byte-capped offline mirror (ingeststore.ts); sqlite rows through
+      parameter binding only (ingestdb.ts)
+- [x] PV0.004 the /ingest bench walking decode → separate → analyze →
+      segment → store with the phase meter (Sol/ingest/ingest.tsx)
+- [x] PV0.005 the typed-URL law: devthink barra <app> lands inside the os on
+      all ten family apps (?arrive handoff, ?independent escape)
+- [x] PV0.006 the 339-test battery green, the 402kb bundle building clean
+
+## wave PV1 — the reference system (the ids, the pointers, the server law)
+
+- [ ] PV1.001 schema upgrade of ingest_documents: owner_id (BIGINT pointer),
+      kind ("reference" | "render" | "upload"), visibility ("private" |
+      "vitrine"), blob pointers for mix and stems, size, sha256 — parameter
+      binding only, mirroring prisma/schema.prisma
+- [ ] PV1.002 the id mint: bigintids.ts — time-ordered 64-bit ids (the big
+      pointers the house law names), zero storage, deterministic tests
+- [ ] PV1.003 the gateway routes of ingest: POST /api/v1/ingest/upload
+      (multipart, streams to the job store, returns the job id), GET
+      /api/v1/ingest/jobs/:id (progress: decode, separate, analyze, segment,
+      store), GET /api/v1/ingest (the shelf rows), GET /api/v1/ingest/:id,
+      DELETE /api/v1/ingest/:id
+- [ ] PV1.004 the server worker ingestworker.ts (node, the gateway lane):
+      decode (audio-decode/wav) → hpss separate → analyze → segmentsof →
+      ingestPcm → wavwriter per stem + mix → blob store — the browser never
+      runs any of it
+- [ ] PV1.005 the blob store contract blobstore.ts: put(stream) → pointer
+      {id, bytes, sha256, kind}, get(id) → stream — the vault law (the
+      storage app owns the engine; the gateway serves it), git-lfs friendly
+- [ ] PV1.006 the job ledger table ingest_jobs (id BIGINT, owner_id, state,
+      progress, error, document_id, created_at, finished_at)
+- [ ] PV1.007 the bench rewired: file → POST upload → poll the job → the
+      phase meter reads the server progress → the document renders — zero
+      dsp on the visitor's machine; the local opt-in path stays behind an
+      explicit "run on this device" key
+- [ ] PV1.008 every document row carries the owner id (the user ingest or
+      the system ia ingest — both stamp the same pointer chain)
+- [ ] PV1.009 the system ingest lane: the ia (or an mcp automation, opt-in)
+      posts the same upload route with the service identity — the reference
+      library grows without a human
+- [ ] PV1.010 tests: bigintids monotonicity, blobstore round trip, worker
+      end-to-end on a synthetic wav, the routes contract with a fake fetch
+
+## wave PV2 — the playback proof (the ingested track plays)
+
+- [ ] PV2.001 the mix and stem wavs ride the blob store; GET
+      /api/v1/blob/:id streams them with the right mime (audio/wav)
+- [ ] PV2.002 the playerbus learns the reference take: the ingested mix
+      loads as a take the bar plays (the same bus the generated takes ride)
+- [ ] PV2.003 the bench document view gains the play key: the stored mix
+      streams through the shared bar (the proof the owner demanded: ingest →
+      play, no re-render)
+- [ ] PV2.004 stem audition: harmonic and percussive playable solo/muted
+      (the stems the worker stored), the conservation audible
+- [ ] PV2.005 the library shelf rows carry the play key too (the ingested
+      references sit beside the generated takes, one grammar)
+- [ ] PV2.006 tests: the wav round trip (store → stream → decode equals the
+      source samples), the bus contract for reference takes
+
+## wave PV3 — the pattern miner (the genre tool the references feed)
+
+- [ ] PV3.001 patternminer.ts: reads the ingested documents of a genre and
+      answers the genre profile — bpm distribution, key pool, chord ladder
+      frequency, onset density curves, band balance, loudness targets
+- [ ] PV3.002 the genre profile document debonair.profile/1 (deterministic,
+      parametrized, versioned) — stored in genre_profiles with the reference
+      ids that fed it (the pointer chain audit-ready)
+- [ ] PV3.003 similarity: the vector distance over frames (cosine on the
+      normalized segment vectors) — nearest references answer a prompt
+- [ ] PV3.004 the miner runs server side (a gateway job like the ingest
+      worker); the browser asks, never computes
+- [ ] PV3.005 the vitrine surfaces the profiles (the genre cards the home
+      shows come from the db, never hardcoded)
+- [ ] PV3.006 tests: the miner on synthetic documents of two genres
+      separates, the profile determinism, the similarity ranking
+
+## wave PV4 — the composer (prompt → similar json → real audio → play)
+
+- [ ] PV4.001 the composer prompt → genre match (genrematrix) → the profile
+      of that genre → a seeded vector plan similar to the references
+- [ ] PV4.002 the render: audioengine renders the plan offline (the existing
+      renderTakeOffline lane) — kick/snare/hats sample-accurate, bass, keys,
+      pads, the arrangement the plan carries
+- [ ] PV4.003 the render job table render_jobs (exists) wired to the worker:
+      queued → rendering → done, the wav lands in the blob store, the track
+      row lands in tracks with the pointers
+- [ ] PV4.004 the generated take plays in the same bar, publishes to the
+      vitrine (the spotify/netflix shelf the owner described) and downloads
+- [ ] PV4.005 the vocal lane grows after the instrumental proof (the
+      SINTESE-VOCAL-AI line), opt-in, never blocking the wave
+- [ ] PV4.006 tests: the same prompt+seed renders the same bytes, the render
+      job lifecycle, the vitrine rows
+
+## wave PV5 — the design reform (debonair wears the devthink index face)
+
+- [ ] PV5.001 screenshot the live os home and every debonair page (the
+      browser session) — the gap list against the index face
+- [ ] PV5.002 the shell chrome: the window, the pin rail and the player bar
+      re-tuned to the os grammar (the trylle surfaces, the fluent shadows,
+      the campaign motion) — no drift tokens
+- [ ] PV5.003 the home: the prompt-first hero over the noir stage retuned,
+      the song grid rows in the streaming grammar (cover, title, genre line,
+      duration, play on hover), the shimmer and the stagger
+- [ ] PV5.004 the ingest bench in the same face (the dropzone, the meter,
+      the cards, the shelf)
+- [ ] PV5.005 the generate/library/studio/settings pages one pass each —
+      short copy, no dots, the same nav law, every key answering
+- [ ] PV5.006 the 404 and the intro re-faced
+- [ ] PV5.007 the live verification: every route of the app inside the power
+      clip and standalone (?independent), screenshots compared
+- [ ] PV5.008 the same face check on light theme
+
+## wave PV6 — the family integration (the engines talk)
+
+- [ ] PV6.001 the gateway app serves the debonair api lane (the routes of
+      PV1/PV3/PV4 ride the gateway the family shares)
+- [ ] PV6.002 the vault stores the blobs (the blobstore pointer resolves
+      through the vault engine when configured, git-lfs backed)
+- [ ] PV6.003 the saddle AVM modalities run the heavy jobs (the worker lane
+      declares the sandbox modality, opt-in per deploy) — the visitor's
+      machine stays clean even at scale
+- [ ] PV6.004 the mcp automation lane (opt-in): an external agent ingests
+      and generates through the same gateway with its own identity
+- [ ] PV6.005 the debonair package.json exports the engine library (the npm
+      face: analyze, hpss, ingest, patternminer, audioengine, wavwriter —
+      zero hardcode, everything configured through options/db)
+
+## wave PV7 — the verification ladder (the proof the owner reads)
+
+- [ ] PV7.001 the full battery green (vitest) on every wave's modules
+- [ ] PV7.002 the typecheck + biome + build clean on every push
+- [ ] PV7.003 the live proof: ingest a real track through the ui, watch the
+      server do the work, press play, hear the mix, hear the stems
+- [ ] PV7.004 the live proof: generate from a genre with references, hear
+      the take, publish to the vitrine
+- [ ] PV7.005 the live proof: devthink barra debonair → the window inside
+      the os, the bench inside it, no flash, one boot
+- [ ] PV7.006 the worklog and the ladder ticked, the wave committed

package/docs/planning.v2.28-completo.md

@@ -0,0 +1,69 @@
+# planning.v2.28-completo — the ladder to the complete debonair app
+
+> owner directive: make the app COMPLETE (suno.com generation x FL studio desk),
+> house tree, no src/, no ui/ folder, doctrine of #oficial 4 + DESIGN_MAP v2.
+> this plan is the single source of truth for the wave that closes the gaps
+> listed in DEBONAI-RULEMAP.md section 7 and DEBONAI-VERSIONS.md backlog.
+> step ladder generated from the live inventory: docs/planning.ladder.md
+
+## where the app stands (inherited, verified this session)
+
+- native app at `debonair/debonair/` (house tree: pure ts engines at the root,
+  Sol/ theme, docs/, tests/). 28 engines + kathesis b2 (spectrum, fingerprint,
+  analyze, vocalsynth). 261 vitest cases green, tsc 0, biome 0. commit 504b8ae
+  on branch kathesis/b2-wave, pushed.
+- served in the sandbox by the next.js gateway (single launcher page, iframe of
+  the built bundle under public/debonair/). nothing is duplicated in the gateway.
+- auth: device flow token persisted (iakadion). pushes land on
+  github.com/wenathlan/devthink.
+
+## gaps this wave closes (the definition of "complete")
+
+| gap (inherited) | wave | delivery |
+|---|---|---|
+| daw editing is cosmetic (algebra exists, ui does not edit) | K3 | timeline editor in seconds: move (drag+snap), trim, split, duplicate, delete, clip selection; piano roll editor over the scheduled notes with add/remove/move/resize/quantize; honest re-schedule through takeevents + audioengine; aria + keyboard paths |
+| no wav / midi / stems writers | K4 | wavwriter.ts (16/24/32f encoder, riff-correct), midiwriter.ts (smf format 1, vlq, tempo meta), stems.ts (per-role stem plans + manifest schema v1); export actions in the studio desk |
+| no live visualization (analyser to canvas) | K5 | spectrum scope + waveform overview wired to the real analyser tap; playhead clock; reduced-motion guard |
+| no server persistence (RenderJob idle) | K6 | gateway api projects (list/upsert/delete) on sqlite via prisma; cloudsync.ts engine (seam: fetch first, sessionStorage fallback, 2.5s timeout like onboardingstate); settings page shows sync state honestly |
+| competitors dissected but not written down | K1 | docs/competitor-dissection.md from the five clones in allan/temp (libsonare, pulsegridstudio, magenta-js, acestep.cpp, heartlib) |
+| planning ladder + version ladder | K2 | this file + docs/planning.ladder.md (900+ steps from the live inventory) |
+
+## waves (task ids continue the worklog ladder)
+
+- K1 — competitor dissection (read-only on allan/temp; writes docs/).
+- K2 — planning: this document + generated ladder.
+- K3 — studio daw editing (pianoroll.ts engine + Sol/studio/timeline + pianoroll ui + tests).
+- K4 — writers: wavwriter.ts, midiwriter.ts, stems.ts + contract tests.
+- K5 — live viz (spectrum scope, waveform overview, clock) on the real analyser.
+- K6 — gateway persistence (api + cloudsync.ts engine + settings surface).
+- K7 — gates: vitest full suite, tsc strict, biome zero; vite build; sync
+  public/debonair; commit as iakadion on kathesis/b3-wave; fetch before push.
+- K8 — browser verification of the served app (agent-browser) + worklog close.
+
+## doctrine invariants every wave must keep
+
+1. engines are pure ts at the root: no DOM, no AudioContext, no storage;
+   tables first, orchestrator last, ~300 correlated logics per file, JSDoc on
+   every export, typed results or error classes with machine codes.
+2. determinism: same prompt + same seed = same take; mulberry32(hashSeed(fnv-1a))
+   is the only rng; editors (pianoroll, timeline) are deterministic algebras.
+3. sol.css is the single design source; windows accent #4cc2ff only in chrome
+   focus, amber #d9962e only in brand/cta; zero emoji icons (lucide only);
+   zero pills; reduced-motion guards; solcss.test.ts must stay green.
+4. ui speaks english, lowercase chrome voice; mono tabular for bpm/key/lufs.
+5. one audible transport: playerbus; studio hushes the bus on mount.
+6. no touch on sibling apps (devthink, cadria, getry, vault, saddle...).
+   getry/vault integration stays an adapter seam, never reimplemented.
+7. gates before any push: biome 0, tsc 0, vitest green. commits as iakadion.
+8. honest ui: no fake metrics, no invented reviews; export is real (wav/midi
+   download of rendered audio), sync states read real endpoints with timeouts.
+
+## acceptance criteria (the wave is done when)
+
+- [ ] all six gaps above closed with green gates.
+- [ ] vitest suite green with the new engine contract tests.
+- [ ] served app (gateway iframe) verified in a real browser: generate a take,
+      open the desk, edit a clip, edit a note, export wav + midi + stems,
+      see the spectrum move, save to cloud, reload, find the take.
+- [ ] worklog carries every task id; version ladder updated (v2.28/2.29/2.30
+      delivered; v2.31 speechalign recording and v3.0 render queue remain).

package/docs/planning.versions.2.0.97-3.0.md

@@ -0,0 +1,48 @@
+# planning.versions — the 2.0.97 → 3.0 ladder of debonair
+
+> the document the previous operation died creating (session corte at L2485-2495 of
+> the context corpus). the ladder runs in houses of ~200-300: each house closes a
+> capability block, ships green (biome 0/0 · tsc 0 · vitest green) and bumps the
+> lockstep version. tree wins; the engine is the debonair root; the family imports
+> the published `@wenathlan/debonair` library — never a path, never a bundle.
+
+## where the house stands (verified 2026-10-12)
+
+- `667c20a` head · katexis b1 + sol v2 trylle foundation · 240 tests green
+- wave b2 (kathesis) landed in this operation: `spectrum.ts`, `fingerprint.ts`,
+  `analyze.ts`, `vocalsynth.ts` + 4 suites → **261 tests green** (26 files)
+
+## the ladder
+
+### house 2.0.97 → 2.0.150 — the kathesis analysis core (this wave, b2)
+- [x] spectrum kernel (fft · hann · chroma · kk correlation)
+- [x] fingerprint identity (constellation · landmarks · db)
+- [x] analyze pipeline (flux tempo · octave law · key · lufs · structure · report.schema v1)
+- [x] formant voice (vowel table · seeded vibrato · syllable grid · level law)
+- [x] enginemap honest refresh
+- [ ] `report.schema.ts` — the json/txt formatters the corpus docs 12/26 prescribe
+- [ ] `restage.ts` — the reference→analysis→plan loop (doc 14→16): a real track's
+      report feeds the arranger so the take follows the reference structure
+
+### house 2.0.150 → 2.0.200 — the daw body
+- [ ] timeline editing for real: drag/split/trim wired to `timelinemodel` on the studio page
+- [ ] piano roll page (`#oficial4` APP-0491..0735: Onboarding/Login/Mixer/Timeline/PianoRoll/Library/Master/Settings)
+- [ ] wav/midi writers (export seam, `<50MB` validation before export)
+- [ ] speechalign → vocal recording with ducking (the mic leg)
+
+### house 2.0.200 → 2.1.0 — the ai acoustics seam
+- [ ] onnxruntime-node seat for the foundation embeddings (clap/beats, int8)
+- [ ] fpcalc/olaf binary orchestration via the saddle contract (node executes, binaries in `tools/bin/`)
+- [ ] whisper.cpp transcription of the vocal stem → the lyricist reads, "A SONORIDADE É INTOCÁVEL"
+- [ ] fingerprint dedup on every render job before the library accepts it
+
+### house 2.1.0 → 3.0 — the family contract
+- [ ] publish `@wenathlan/debonair` (npm/ghcr) — the engine leaves the house
+- [ ] devthink music/musicstudio imports the published engine (no duplication)
+- [ ] cadria/getry/vault consume the audio primitives through the same library
+- [ ] 44.1k/48k master spec locked: −14 lufs streaming · −1 dbtp · anti-nan · pre-export validation
+
+## the laws this ladder obeys
+1. tree wins · 2. one domain per file ≤300 lines · 3. tables at the top, orchestrator last
+4. seeded determinism in everything generated · 5. zero hardcode, zero consumer data in the engine
+6. gates green before any bump · 7. commits as iakadion · 8. actions by tag, never sha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/debonair",
-  "version": "2.0.136",
+  "version": "2.0.138",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"