Immutable items

[cinnamon-bun]

This idea is very old, please see the comments for newer ideas

---

---

Goal

Allow documents to be (optionally) immutable, meaning you can't overwrite them with newer versions.

How

Paths could contain a special marker which will be replaced with the document's hash:

/moderation-actions/{id}
    will get expanded to
/moderation-actions/#xxxxxxHashOfItemxxxxxx

Because it's hard/impossible to create hash collisions, nobody will be able to create another document version with the same hash, so this document version can never be overwritten with a newer one.

New concepts

This splits the idea of paths into two:

• Path Templates - before replacing the id with the hash
• Expanded Paths - after replacing

Documents that are being signed or sent across the wire only have Path Templates. The path templates are kept forever as part of the original item. They are not used for path lookups and queries (?)

Expanded paths are derived state, computed by the Storage when receiving documents. They are used for all kinds of path lookups and queries.

Details

We'll need to reserve a few characters for this, both for the Path Templates and the Expanded Paths.

You must not be able to create an Expanded Path directly, so in this example # would have to be disallowed from Path Templates.

Tasks

• [ ] Decide on characters for Path Templates and Expanded Paths. See this comment for details on the available characters
• [ ] Disallow the expanded-character from Path Templates, in the Validator
• [ ] Update all the Storage classes to understand the two kinds of paths
• [ ] Figure out which paths should appear in which situations (querying etc)

Bonus

Once we have these two kinds of path, we can add another expansion which is a shorthand for the author's own key:

/~@@/about/name
    expands to
/~@meee.xxxxxxxxxx/about/name

This is just an optimization to save space from repeating the author's full address all the time. It might not be worth the extra complexity.

[cinnamon-bun]

The above idea is complex and there's an easier way to make immutable documents: just add an immutable property. But let's look at the big picture first.

Why immutability?

Immutable docs would be useful in some situations...

• A "constitution" or "manifest" JSON doc that declares the policies of a workspace, and nobody can alter it later.
• Situations where the honor system is not quite enough, and we don't trust people to not mess with their old documents: voting, choosing a moderator? Board games?
• Situations where you want to leave an audit log to improve trust: moderator actions like blocking people, money-like systems
• If you're storing content-addressed blobs in Earthstar, named after their hashes, you'd have no reason to ever modify them but you might want to delete them.
• You could publish Earthstar apps as javascript files inside Earthstar. Immutability would help with security, so people know the file will never change out from underneath them.

Deletability, permanence, ephemerality

Sometimes we might want immutable docs to be deletable, and sometimes permanent. Deletable docs can be overwritten exactly once with an empty document. Permanent docs can not be overwritten with anything.

It should also be possible to combine this with ephemeral docs, to create immutable docs that expire and go away. After they go away you could write a new one to the same path, so it's only sort of temporarily immutable.

Proposal: a new immutable property on docs

This optional property would only be present on immutable docs. It might have two possible values: one for deletable immutable docs and another for non-deletable immutable docs.

{
    path: '/my/path/here.txt'
    immutable: true,   // or maybe "deletable" | "nondeletable"
    // ...other document properties...
}

Pro:

• self-documenting
• simple
• can be added to format es.4 without breaking old data

Con:

• Docs get a little bit bigger
• I dislike optional properties in objects, but it makes sense here since immutable docs will be uncommon and we don't want every doc to get bigger

Problems with immutable docs

Someone could put an immutable doc in the way of some other doc that you wanted to make, if it had a shared path (a path not owned by anyone).

Maybe we could require immutable docs to have something special in their path, similar to how ephemeral docs have ! in their path.

Weird extra idea: an "edit countdown"

Or instead we could add an optional property called remainingEdits which holds a small integer. Immutable docs have 0 remaining edits. The number counts down every time the doc is edited and it can't go below zero.

I'm not sure exactly what use cases this would allow, but apps might be able to do something clever with it. For example it could create a sort of scarcity if each person had a doc that they could only edit five times, meaning they would want to only use it in serious situations.