site/STORAGE.md

# gandora storage contract

The page keeps everything through one object, `db`, in `index.html`. Today it is IndexedDB in the browser; a backend
replaces it by implementing the same calls and pointing `db` at the new implementation. Nothing else in the page
touches storage (`brain.js` reads through `db.all()` and `db.get()` too).

```
db.put(row, store = "tracks")      // create or replace, keyed by row.id
db.get(id, store = "tracks")       // one row, or null
db.all(store = "tracks")           // every row, newest first (tracks by `made`, stations by `last`)
db.del(id, store = "tracks")
db.open()                          // internal; a backend adapter can drop it
```

Three stores: `tracks`, `stations`, `tapes`. `db.all("tapes")` puts a virtual tape first, `{ id: "kept", name: "KEPT",
ids: [every kept track, oldest first], virtual: true }`, built from the tracks; `db.put` ignores it and `db.get("kept",
"tapes")` is null (the page's `tapeById` knows).

## tracks

```
{
  id:        "1760998800000-211979153",   // spec.made + "-" + hash32(title); stable, made by the page
  made:      1760998800000,               // ms epoch, when the DJ wrote it
  kept:      false,                       // pinned by KEEP (the only pin)
  plays:     3,                           // play starts + loop passes
  blob:      Blob,                        // the audio (FLAC from Venice, mp3 from Runware); a backend may return { url } instead
  spec: {                                 // the song on paper: enough to re-render it anywhere
    title, tags, lyrics, bpm, key, energy, line,   // what the DJ wrote (tags = the music prompt, <= 500 chars)
    seed, station, stationId,                      // where it came from
    reaction: "🔥 ❤️ \"less snare\" [skipped]",     // the listener's reactions, in order; words quoted, skips bracketed
    guess: 0.71,                                   // the taste net's prediction when it was cooked (optional)
    plays, id, made                                // mirrored for convenience
  }
}
```

## stations

```
{
  id:      "s-1760998800000-211979153",   // "s-" + ms + hash32(seed)
  seed:    "rainy trains",
  name:    "Platform Nine",               // chosen by the DJ on the first track, then stable
  taste:   { like: [...], avoid: [...], notes: [...] },   // last 8 of each, in words, fed to the DJ
  history: [ { id, title, tags, bpm, key, energy, reaction, made } ],   // last 8 tracks, no blobs
  made:    1760998800000,
  last:    1761002400000,                 // touched on every play and reaction
  played:  23
}
```

## tapes

```
{
  id:      "tape-1761002400000",
  name:    "late trains",
  ids:     [ "1760998800000-211979153", ... ],   // track ids, in order
  made:    1761002400000,
  last:    1761002400000
}
```

## what a backend adds

- identity: rows are per listener; `/user/station/track` links need the listener in the key
- `blob` as a URL the `<audio>` element and the Web Audio analyser can load (same-origin or CORS-enabled)
- sync: the page calls `db.all()` freely (library, taste, a station's tracks, play counts), so cache on the client and
  keep `all()` cheap; `db.get()` is on the playback path (stepping back and forward, tapes), so keep it fast too

## what stays on the page

The taste net (`brain.js`) trains in the browser from `db.all()` rows; it needs only `spec` + `kept` + `plays`.
Share links (`?t=`) carry a spec, not an id, so they work with no backend at all; with one, a link can carry the id
and the backend's audio instead of re-rendering.