File over app
calternal keeps User data and User metadata as plain files in Home. The Index helps calternal find and sort those files. The Index can be rebuilt from the Data directory, except for Security state.
What is a file
Section titled “What is a file”A file is the source of truth for its content. Notes are Markdown files. Events use iCalendar files when an external provider owns them. Photo metadata can use an XMP Sidecar next to the photo.
A Collection file in .calternal/ describes a set of objects, such as an album or a saved search. A Reference in a Collection file uses the file path and its content hash.
What is Derived data
Section titled “What is Derived data”Derived data is computed from files. Examples are thumbnails, embeddings, and the search index. calternal can rebuild this data. It does not store Derived data in Home.
The Index is also rebuildable from the Data directory. It speeds up searches and other file operations. It is not the source of truth for file content.
What is Security state
Section titled “What is Security state”Security state is the exception to the file rule. It includes accounts, credentials, sessions, Roles, shares, permissions, and Plugin enablement. Security state lives only in the Index. calternal cannot rebuild it from files.
A file cannot grant access. A User or an agent cannot add access by editing a file in Home.
Who writes files
Section titled “Who writes files”The server is the single writer of the Data directory. Browsers, Apple clients, the CLI, and Agent containers send changes to the server through a supported client interface. They do not write to the Data directory.
This rule keeps file changes safe. The server writes a new file, checks it, and then replaces the old file in one operation.