Drive

VoltDrive is the part of Volt4 that models a synchronised, shared file system: a logical tree of paths and files whose contents are kept consistent through the same sync database machinery as other collaborative data, while still looking like normal files and folders to tools and users.

Two resource kinds work together in the implementation:

Drive database

The drive database is a synapse resource that also carries the volt:drive-database kind. That synapse holds the replicated drive state (documents for file content and indexing, coordinated like any other synapse-backed data).

The drive database resource also describes the folder-sync settings that are used when a Volt keeps a directory on disk in step with that synapse: glob-based include and exclude lists, a maximum file size, whether hidden files are included, and whether binary files are skipped. Those options apply to the Volt’s embedded folder synchronisation logic.

Drive instance

A drive instance (volt:drive-instance) is a separate resource that synchronises a drive database to a local folder path on the machine running that Volt process. Each instance records which synapse (the drive database) to follow as well as which folder to mirror.

An instance may also record how to reach the synapse when it does not live on the same Volt: remote Volt address details, relay settings, and related fields. So one physical Volt can run folder sync against a drive database that is authoritative on another Volt, as long as connectivity and policy allow it.

When a Volt starts, its drive subsystem loads every drive instance resource, initialises a worker for each, and keeps that worker running until the instance is removed or the Volt stops. Adding, updating, or removing a drive instance resource is reflected on the event bus, so new or changed instances are picked up without a full restart.

How file content is stored

Each file in a drive is a synapse document. The document’s schema decides how the body is stored; folder sync does not re-sniff an existing document on every pass.

Text files

Text files are stored as a Yjs text root named content. Clients can edit them collaboratively through the usual synapse / SyncDocument path. Folder sync treats a new file as text when it is empty, contains no NUL bytes, and the start of the file is valid UTF-8.

Binary files

Binary files are stored as synapse blob documents. The payload lives in the synapse blob store, content-addressed by SHA-256 of the raw bytes (unpadded base64url). There is no Yjs shared type for the body: replacing a binary file uploads a new blob and rebinds the document’s __hash.

A new local file is treated as binary if it contains a NUL byte, or if the first 2 KiB (or the whole file, if smaller) is not valid UTF-8.

By default folder sync skips binary files. Pass --include-binary-files to create-drive-instance (or set the matching drive-database attribute) to replicate them. The same skip also applies to blob documents that arrive from another replica, so a drive that opts out of binary files will not materialise remote binaries as empty placeholders.

Once a document exists, its schema is authoritative. Empty files always look like text when sniffed, and repairing invalid UTF-8 can make a file look like text later; folder sync still hashes and transfers an existing blob document as a blob.

Size and hidden files

Files larger than the configured maximum (default 1 MB) are skipped, both when they appear on disk and when a remote document advertises a larger size. Files and folders whose names begin with . are skipped unless hidden files are included. .volt-drive, .git, and .DS_Store are always excluded.

Document readiness

Synapse metadata (path, size, __hash, schema) can replicate ahead of the file body. Folder sync waits until this Volt reports the document as READY — the advertised __hash matches content this Volt actually holds — before writing the file to disk. For a blob that means the bytes are in the local blob store; for text it means the Yjs document has been hashed to match __hash.

Legacy binary documents

Drives created before blob storage kept binary bodies as a Yjs array of byte values. Folder sync no longer reads or writes that format: the local file is left as it is, and the document is not opened. New binary files are always blob documents.

Policy and safety

Ordinary access to the data inside a drive database is governed by Volt policy like other databases: for example volt:database-read and volt:database-write on the underlying resource, as described under policy. Reading and writing blob payloads uses those same database permissions via the synapse blob APIs.

Creating or updating a drive instance is done via the Drive API SaveDriveInstance API. This is a privileged API call, because it entails access to the local disk on the machine that is running the Volt. Callers need the explicit volt:api-call permission granted for the volt:save-drive-instance permission.

Sharing the contents of a drive with other identities is still expressed through normal policy on the drive database (synapse) resource—for example database read or write—backed by verifiable credentials as elsewhere on the platform.

What you get in practice

One path namespace inside a drive database — familiar hierarchical names for files and directories.
Live replication of text as Yjs documents, and of binary files as content-addressed blobs, between clients and Volts that participate in the same synapse.
Optional desktop sync — each drive instance ties one synapse-backed drive to one local directory on a Volt host, with include/exclude, file-size, hidden-file, and binary-file rules defined on the drive database resource.