FUSE Filesystem - iGent Concert

Chronicle implements the full FUSE (Filesystem in Userspace) interface, presenting a standard POSIX filesystem to applications.

POSIX Compliance

Chronicle supports all standard file operations:

Operation	FUSE Method	Description
`open()`	`open`	Open file for reading/writing
`read()`	`read`	Read file content
`write()`	`write`	Write file content (creates new iteration)
`mkdir()`	`mkdir`	Create directory
`unlink()`	`unlink`	Delete file (creates deletion iteration)
`rename()`	`rename`	Rename/move file
`chmod()`	`setattr`	Change permissions
`stat()`	`getattr`	Get file metadata
`readdir()`	`readdir`	List directory contents
`symlink()`	`symlink`	Create symbolic link

Versioning

Every write operation creates a new iteration:

1. Agent writes to workspace/main.py 2. Chronicle intercepts the write() call 3. New content is stored in CAS (BLAKE3 hashed, Zstd compressed) 4. A new iteration row is inserted in SQLite 5. The file's content_hash and iteration counter are updated 6. The write() call returns to the agent

This is transparent — the agent sees a normal filesystem.

Magic File API

Chronicle exposes version history via virtual paths under .chronicle/:

class="token comment"># Query file history
cat workspace/.chronicle/query/main.py
class="token comment"># Returns JSON array of iterations with timestamps and hashes

class="token comment"># Access file at specific iteration
cat workspace/.chronicle/at/42/main.py
class="token comment"># Returns the content as it was at iteration 42

Performance

Metadata Cache

An in-memory DashMap cache eliminates SQLite queries for hot-path metadata lookups (getattr, readdir). Cache entries are invalidated on writes.

Read Cache

Recently read file content is cached in memory with LRU eviction, avoiding repeated CAS lookups for frequently accessed files.

Backends

fuser (default)

Uses the fuser Rust crate which interfaces with macFUSE (macOS) or libfuse (Linux):

Mature and well-tested
Requires macFUSE kernel extension on macOS
Full POSIX support

FSKit (historical note)

Native macOS filesystem provider — no kernel extension required:

Uses fskit-rs Rust bindings
No SIP (System Integrity Protection) issues
Automatic detection on supported macOS versions
Build with --no-default-features --features native-fskit