@wenathlan/debonair 2.0.133 → 2.0.135

package/docs/planning.pipeline.md

@@ -1,198 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 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