IDs, not paths

Every item is named by an ID. A name is only a label.

View as Markdown

An agent that addresses files by path breaks the moment someone renames a folder. flie never addresses anything by path.

fld_787MMXNSG29ZTR4D4XG0FZN11J   a folder
fil_2Q8Y0H4VJ1R6B5N3KXW7TCDM9A   a file
  • An ID is identity; a name is a label. Two items in one folder may share a name, and nothing is ever addressed or replaced by name.
  • Every reference is an ID. whoami gives your root folder's ID. To go from a name to an item, list or search a folder whose ID you hold.
  • A path is refused with obsolete_ref, so a stale habit fails loudly instead of reaching the wrong file.

Revisions

A file's revision turns only when its bytes change. Renaming or moving it leaves the revision alone, so a write prepared before someone reorganized the folder still applies.

write, edit, rename, move, remove, copy and restore each state the revision they expect. If the item moved on in the meantime, the change is refused with revision_conflict and nothing is written. The agent reads again and decides. Two agents never silently overwrite each other.

Nothing is lost by a write

Every change to a file's bytes is a content version, and history lists them. read names a past version to get its bytes back. trash moves an item into the trash, and restore puts it back.

On this page