Episode 03 --- Everything Is Content-Addressed
Working YouTube title:
Why SHA-256? The Idea Underneath Every Muse Object
Thumbnail thought:
the name IS the content.
Target runtime: ~7:30
[0:00--0:20] COLD OPEN
[CAMERA --- same terminal energy as Episode 02, but a fresh, empty repo this time.]
GABRIEL:
Last episode I kept saying "the folder name is the hash" and moving on.
[beat]
No more moving on.
[TITLE CARD --- fast]
EVERYTHING IS CONTENT-ADDRESSED
[Music enters.]
[0:20--1:05] SAME CONTENT, SAME ADDRESS
[TERMINAL]
$ echo "hello" > a.txt
$ echo "hello" > b.txt
$ muse hash-object a.txt
sha256:2cf8d8...
$ muse hash-object b.txt
sha256:2cf8d8...
GABRIEL VO:
Two different files. Two different names. Identical hash.
[beat]
$ echo "hello world" > c.txt
$ muse hash-object c.txt
sha256:0bd690...
GABRIEL:
Change one character of content, and the address changes completely.
[CAMERA]
Nobody assigned these IDs. Nothing incremented a counter. The address is a computation over the bytes. Same bytes, anywhere, ever, always produce the same address.
[ON SCREEN]
THE NAME ISN'T A LABEL. IT'S A FINGERPRINT.
[1:05--1:50] DEDUPLICATION FOR FREE
[TERMINAL]
$ muse code add a.txt b.txt c.txt
$ muse commit -m "Three files, one duplicate content"
$ muse ls-files
a.txt sha256:2cf8d8...
b.txt sha256:2cf8d8...
c.txt sha256:0bd690...
GABRIEL VO:
Three tracked files. Two unique hashes.
[beat]
$ muse verify
objects_checked: 2
GABRIEL:
a.txt and b.txt don't just look the same to Muse --- they are
the same object, on disk, once. Muse isn't smart enough to notice they
match and decide to dedupe them.
[beat]
There was never a second copy to begin with. Identical content literally cannot be stored twice --- it would just be the same address, computed twice.
[1:50--2:40] WHAT'S ACTUALLY ON DISK
[TERMINAL]
$ od -c .muse/objects/sha256/0b/d690...
blob 12 \0 h e l l o w o r l d \n
GABRIEL VO:
Here's something I glossed over last episode. That's not the raw file.
[SCREEN --- format highlighted: blob / size / null byte /
content]
It's a small header --- the object type, the byte length, a null byte --- and then the content. The hash is computed over all of that, header included.
[beat]
$ shasum -a 256 c.txt
a94890...
$ muse hash-object c.txt
0bd690...
GABRIEL:
Which is why a plain shasum on the file gives you a different
hash than Muse does. It's not a bug. It's hashing a different, typed
thing --- "this is a blob, this many bytes, this content" --- not just
raw bytes with no idea what they are.
[CAMERA]
If you've used Git, this will feel familiar. It's the same trick, for the same reason.
[2:40--3:35] TAMPER DETECTION
[TERMINAL]
$ printf 'blob 12\0corrupted!!' > .muse/objects/sha256/0b/d690...
GABRIEL VO:
I just hand-edited a stored object directly on disk. Let's see what Muse thinks about that.
$ muse verify
[SCREEN --- real error, not a mockup]
❌ hash mismatch:
expected sha256:0bd690...
got sha256:e3becf...
data corruption detected
GABRIEL:
It didn't just say "something's wrong somewhere." It named the exact object, the hash it expected, and the hash it actually got.
[beat]
Because the filename is a claim. "My content hashes to this." Verify is just Muse checking whether that claim still holds.
[3:35--4:20] SNAPSHOTS: STATE AS ONE ADDRESS
[SCREEN --- callback to Episode 02's read-snapshot output]
{
"manifest": {
"hello.py": "sha256:e79677..."
}
}
GABRIEL VO:
Remember this from last episode. A snapshot is a map --- path, to the hash of that path's content.
[beat]
But the manifest itself is content too. It gets hashed. That hash
is the snapshot_id.
[SCREEN --- diagram: file hash → manifest → snapshot hash]
So one single ID --- the snapshot ID --- transitively commits to every file, at every path, in the entire tree, at that moment. Change one byte in one file anywhere in the project, and the snapshot ID changes too. There's no way to change the content without changing the address that describes it.
[4:20--5:20] THE COMMIT DAG
[SCREEN --- callback to Episode 02's merge commit JSON]
{
"parent_commit_id": "sha256:e5e7da...",
"parent2_commit_id": "sha256:09218e..."
}
GABRIEL:
Two parents. We saw this last episode and moved on. Here's why it has to be exactly this shape.
[SCREEN --- simple graph animation: two branches diverging from one commit, reconverging at a merge commit]
A list can't represent this. A list has one predecessor per entry, by definition. But two branches genuinely both happened --- independently, concurrently, neither aware of the other --- and then, at some point, history needs to say "these two paths are now one."
[beat]
That requires a graph. Specifically, a directed, acyclic one --- commits only ever point backward, to what already existed, never forward, never in a loop.
[CAMERA]
Every branch is a name for one point in that graph. Every merge is a new commit with more than one parent. The whole shape of Muse's history --- branch, merge, rebase, cherry-pick --- falls out of that one structural decision.
[5:20--6:10] WHY THIS MATTERS FOR MERGE
[CAMERA]
Put the two ideas together for a second.
Content addressing means identical state always produces an identical hash. The commit DAG means every commit knows exactly which state it started from.
[beat]
So when two branches merge, Muse isn't guessing whether they touched "the same part of the file" the way a text-based diff has to.
[SCREEN --- brief flash forward to Episode 01's clean merge output]
It can ask a much sharper question: did these two histories actually modify the same object, starting from the same common ancestor, or didn't they?
[beat]
That question --- and how Muse actually answers it --- is Episode 08. For now, just notice: it's only answerable at all because every piece of state has an address that's derived from its content, not assigned to it.
[6:10--6:45] THE POINT
[CAMERA]
Three ideas, and they're not really three separate features.
[ON SCREEN --- one at a time]
OBJECT --- identity derived from content.
SNAPSHOT --- structure derived from objects.
COMMIT DAG --- history derived from snapshots.
Each layer's identity is computed from the layer below it. Nothing in this stack is assigned, guessed, or trusted on faith.
[6:45--7:20] OUT
[TERMINAL --- muse read-commit, the author field highlighted]
GABRIEL VO:
We now know exactly what a commit's content is, and exactly how we'd know if it changed.
[beat]
But we haven't asked who's allowed to write one. Or how you'd prove, cryptographically, that a specific commit really came from you --- or from a specific agent, running a specific model.
[CAMERA.]
Next episode: identity, without a single password anywhere in the system.
[CUT TO BLACK]
musehub.ai
Production Notes
Episode 03 is the season's first genuinely conceptual episode --- no new workflow, no new feature, just one idea examined from every angle. The risk is drifting into a whiteboard lecture. The guardrail: every claim gets a real terminal command proving it before moving to the next claim.
Opening
Directly answer the debt from Episode 02's closing line. Don't re-explain what a hash is from first principles --- the audience for this series already knows what SHA-256 is. What they don't know yet is why Muse hangs its entire identity model on it. Get to the first real command inside twenty seconds.
Every Claim Needs a Receipt, In Order
This episode makes four escalating claims: identical content shares an address; that address is computed, not assigned; the object format has a real, inspectable shape; corruption is detectable, not just theoretically but with a real error naming the exact object. Each claim's receipt must appear immediately after the claim, not batched at the end. This is the episode where "show real Muse constantly" matters most, because everything being said is otherwise invisible.
The shasum Moment Is Load-Bearing
The beat where a plain shasum on a file produces a different hash
than muse hash-object is one of the most concrete, specific,
non-obvious things in the whole season so far. Don't rush past it --
it's the moment a viewer who already knows what SHA-256 is learns
something they didn't already know about how Muse specifically uses
it.
Callbacks, Not Re-Explanations
The snapshot and commit-DAG sections both reuse real JSON output Episode 02 already showed. Cut back to that exact footage rather than re-typing the same commands --- the repetition of the artifact reinforces continuity; re-running the commands would just feel like padding.
The Seed
The viewer arrives thinking:
Okay, hashes, I get it, everything's content-addressed, sure.
They should leave thinking:
Wait --- if identity is just math over content, what happens when the thing being identified is a person, or an agent, and not a file?
That's Episode 04, and the final shot --- a commit's blank author
field waiting to mean something more --- should point straight at it.