← All notes
Architecture

Immutable versions, mutable head

A registry has to answer two different questions about the same package, and one row cannot do both.

A registry gets asked two questions that pull in opposite directions. "What is the latest version of this agent?" wants a record that changes. "Give me exactly what 1.2.0 was" wants a record that never does.

Norien stores both. Every publish writes an immutable version row capturing the full manifest as submitted, and updates a mutable head row pointing at the newest one. Reading a pinned version reads the version row and gets precisely what was published; reading a slug reads the head.

What this buys

Republishing an existing version is rejected rather than accepted-and-overwritten, so an install that worked yesterday works today. Deleting an agent soft-deletes the head and permanently reserves the slug — an abandoned name can never be claimed by someone else and quietly become a different thing.

It also makes the history free. Version listings, changelogs, and diffs are queries against rows that already exist rather than a separate audit system layered on afterwards.