# Content and history

A file name answers “where is it?”.
A content ID answers “which bytes?”.
Keeping these questions separate lets two files share a payload and lets a file change without changing its ID.

## Three levels of identity

A catalog node has an integer ID, a parent and a name.
Renaming or moving it keeps its ID.
Updating a file changes the payload it refers to.

A payload has a digest of all its original bytes.
The same bytes produce the same digest regardless of their file name, chunk sizes or compression.
Changing the bytes creates a different payload.

A payload consists of chunks.
FastCDC chooses chunk cuts from the content rather than fixed byte positions.
An edit can therefore reuse chunks from the previous version instead of storing the whole file again.
The amount of reuse depends on the content and the chunk settings.

Compression acts on individual chunks after hashing.
Two payloads can share a chunk even if they were prepared with different compression settings.
The stored copy need not use the codec requested by the later preparation.

## Why preparation happens before the transaction

Reading an upload, hashing it and trying compression can take much longer than updating a record.
Preparation separates that work from the database write transaction.
Publication checks the prepared bytes again, then stores new chunks and references existing ones.

This also puts resource decisions in the application.
An application can reject a large upload before starting a transaction, bound temporary storage and close prepared content after publication.
It must still allow for metadata memory and concurrent requests.

## Two meanings of history

An old record can store only a digest.
After deletion, that record still describes the old document but resolving its digest through the current store fails.
This permits a history of names and events without keeping the binary content.

A native snapshot instead points to an earlier store state.
That state still reaches its manifests and chunk data.
Deleting from the current state leaves the snapshot readable, including after compaction.

The Yggdrasil xitdb adapter saves native application states.
Its historical commits therefore preserve content, not just names and digest strings.

## Deletion is not erasure

Removing a catalog file leaves its payload available.
Deleting a payload removes it from the selected store and drops chunks that no other payload there uses.
Neither operation shrinks the database file.

Compaction copies reachable native data.
Old snapshots can make deleted content reachable, so compaction is not a command to erase all past copies.
The original database file, backups, replicas and filesystem snapshots can also contain the bytes.

This distinction matters when history and deletion have competing requirements.
An audit trail of digest strings can survive loss of content.
A readable historical snapshot cannot.

See [How to delete content and reclaim space](deletion.adoc) for the application steps.

## Branches need an explicit merge policy

Two branches can allocate the same automatic file ID for different files.
The catalog also maintains child indexes, reverse payload indexes and revisions.
Merging its internal maps independently can break those relationships.

Applications that merge branches need a policy for file identity and catalog conflicts.
xitstash does not supply that merger.
Application-selected IDs address ID collisions, not the rest of the merge.