Guidebook/Act 1 — The Collection

Chapter 01

Ten thousand songs, zero structure

Meet Maya. Fifteen years of playlists, three dead platforms, one rule for the app she's finally building herself — and the one-line function that makes her collection permanent.

Maya
Mints her first atom — the song that started everything
You
Derive real, permanent atom IDs on your laptop. No wallet, no gas.
Teaches
atoms · deterministic IDs · @0xintuition/ids
Maya checks her phone on a wet, neon-lit night street outside the glowing Fillmore marquee.

Maya can tell you where she was the first time she heard "Kerala."

The Fillmore, San Francisco, 2017. Bonobo touring Migration. She can tell you the song that came before it and the one that came after, because she wrote the setlist down on her phone on the walk home — the way she's written everything down for fifteen years.

What she can't tell you is where that note is now.

Every place she has ever organized her music eventually shut down, exported a .csv in a format nothing else reads, and told her to start over. Ten thousand songs. Fifteen years of shows. Zero structure that survived.

Maya is a developer. So this weekend she stops waiting for someone else to fix it and starts building the thing herself. She's calling it Crate — and this guidebook is the story of building it, one real piece of the Intuition stack per chapter, with you writing the same code she does.

The rule Crate has to follow#

Before the first import, Maya writes one rule on a sticky note and presses it to her monitor:

Nothing in Crate can depend on Crate existing. If the app dies, the collection has to still mean something — to another app, to another person, to a future Maya.

This is a harder rule than it sounds. Every ID in every database she's ever used was minted by the database. Rdio's playlist IDs meant nothing to Google. Her spreadsheet's row numbers mean nothing to anyone. Identity was always on loan from the platform — which is exactly why the platform dying always cost her everything.

So the first question isn't "how do I store a song?" It's:

How does a song get a name that no platform owns?

Maya's desk at night: a handwritten rule on a sticky note stuck to a monitor, beside vinyl records, a mug, and printouts.

A thing gets its name from its own bytes#

This is the question the Intuition packages start with. An atom is any piece of data — a song, an artist, a venue, a URL — and its ID isn't assigned by a server. It's derived from the data itself:

crate/first-atom.ts 
import { calculateAtomId } from "@0xintuition/ids";

const id = calculateAtomId("hello");
// 0xa0e157e5fa1b17d3b54ec73622ce3317296920a06502661617613d59f58e947e

Salted keccak256 over the bytes. A pure function — no wallet, no gas, no network call, no account. Run it and you have a 32-byte name that is mathematically the same in every app that ever computes it.

Maya doesn't trust it yet. Good — neither should you.

This is the property Maya has been missing for fifteen years. If the ID of "Kerala" is derived from what "Kerala" is, then Crate dying doesn't orphan the record. Any future app that hashes the same bytes finds the same atom.

Nothing migrates, because nothing has to.

The first record in the crate#

There's only one candidate for the first atom. Maya types the song that started it all:

crate/kerala.ts 
import { calculateAtomId } from "@0xintuition/ids";

const kerala = calculateAtomId("Kerala — Bonobo");
// 0xbdf3c1c19dea6e904e57161c9f2cd674c5c440221eced4755b744e89b3859644

That hex string is real — run the code and you'll land on the same one. As of this line, "Kerala" has a permanent name that belongs to no platform, no company, and no database. It belongs to the bytes.

She adds a handful more — the artist, the genre she'd file it under, the venue where she heard it (a URL is a perfectly good atom):

crate/the-first-shelf.ts 
calculateAtomId("Bonobo");
calculateAtomId("Downtempo");
// 0xf4a6182c09d0ed5c7a3e2b78aa49ca89cd6151c6eb9035bafd07f32734c2ea6d

calculateAtomId("https://thefillmore.com");
// 0xfb6196cc951fd384a990681cc98a43e612a2f4cc2743c1b0001f5cf39f588809

Five minutes in, and the crate has its first shelf: a song, an artist, a genre, a place. Each one permanent. Each one free.

Where this is going#

A pile of atoms isn't a collection yet — what made Maya's dead playlists valuable was never the tracks, it was the relationships: this song is by that artist, this song belongs on that list, this song was heard live at that venue. In the graph, relationships are triples, and in a few chapters Maya's crate will start looking like this:

Kerala — createdBy → Bonobo
Kerala — hasCategory → Downtempo
Kerala — listedIn → Heard Live at The Fillmore

Every one of those verbs comes from a shared registry the whole graph speaks. But that's ahead of us. There's a more immediate problem first: "Kerala — Bonobo" is a string Maya invented. If someone else types "Kerala by Bonobo", they get a different atom for the same song — and the whole point is convergence.

Which raises next chapter's question: what is a song, officially? The answer involves inheriting fifteen years of settled vocabulary from schema.org, and it's a better story than it sounds.