Crate coven_database 

The store’s SQLite database, protected internal tables and app migrations.

DatabaseBuilder opens a store with one locked writer and read-only connections, or with read-only connections alone. App SQL runs inside the borrowed MigrationContext or SqlContext; no raw connection leaves its owner. A local write commits its app rows, unsigned record and merge metadata together on the writer connection.

Modules

operation_kind

The journal kind of each operation coven runs, and the started_by of those coven starts on its own. Sync gives each kind its steps; the database finds invites’ rows itself, for coven_invites and to end them when the installation stops for good.

slot_json

A slot as the JSON coven keeps it in: its number. For #[serde(with = "coven_database::slot_json")].

test_utils

Schema fixtures and crash checkpoints for tests of the production database.

types

Traits dealing with SQLite data types.

Macros

named_params

A macro making it more convenient to pass lists of named parameters as a &[(&str, &dyn ToSql)].

params

A macro making it more convenient to pass longer lists of parameters as a &[&dyn ToSql].

Structs

AdminEffect

Membership and required reload work installed with an authorized admin slot.

AttemptCommits

Every commit made outside one attempt since it began, kept until the attempt names the rows its wait depends on.

BoundaryCoverage

A checked raise or reset and its authenticated snapshot coverage.

BulkSqlContext

App SQL inside one bulk write (§4): it changes device-local tables alone, and may read any table app SQL reads. Returning an error rolls back every statement. This borrowed context cannot change the transaction, access coven’s tables or write a synced one.

CacheBytes

The cache’s bytes: every declared namespace’s, and the partial downloads pins left, which the cache neither counts nor evicts.

CacheReservation

Bytes reserved for one file’s whole encrypted cache file while it is written, until a prepared pin takes it (§17.8).

ChangeSource

An original row change or direct execution target used as data (§9.5, §9.6).

Circle

A circle the local member belongs to (E12).

CircleMemberInfo

An active store member in a circle (E12).

Claim

A claim retains every attempt, including attempts that lost contention.

ClaimAttempt

A create-once request, persisted before the provider is called.

ClaimBytes

Bounded reads of the current attempt’s durable ciphertext.

ClaimUpload

Durable transfer state for the current attempt’s exact sealed bytes.

ColumnChange

One column of a change, retaining its original parent generations privately.

CommitScope

Commits made by database calls that a CommitScope::run future starts belong to that scope. Calls started from other tasks, including tasks the future spawns, are outside it.

CopyReservation

The copies one call to make files device-only is writing, which no other write’s removal takes while it is held or a step it runs is under way. Once both end, whatever became of the call, the next write removes those its switch didn’t keep.

Database

Shared ownership of the database, as its writer or a read-only handle (Database<ReadOnly>), which reads the store through the same calls and cannot write synced rows or migrate. A read-only handle’s connections can change only local cache metadata, and its shared store lock prevents deletion until all of them close. Closing any clone closes them all.

DatabaseBuilder

Choices needed to open the database part of a store.

DatabaseChanges

A live commit observation; coalesces changes and ends when the writer closes.

DeviceInfo

One of a member’s device ids in the committed prefix (E9).

DeviceOnlyCopy

A cloud file to make device-only here: its id, the stored bytes its copy was downloaded from, the copy’s path, which becomes the original this device records, and the hashes of the bytes written to it, which a later move to the cloud checks the copy against (§17.3).

DownloadedWriteStream

A checked write header and its audience streams. The database commits only after sync confirms authentication. Parts follow the header’s order and count.

FileCandidate

A fixed file path awaiting a storage-deletion decision (§17.10).

FileColumn

A column holding a file’s id, or NULL (§17.2, E2). It references the file as a foreign key references its parent.

FileDatabase

File queue and cache access, on the store’s writer or a read-only handle (FileDatabase<ReadOnly>), which reads and caches files and can change only its local cache metadata. The upload and pin queue and the file records are the writer’s. Construct beside the database at the application composition root.

FileHasher

Hashes a file’s bytes as they pass, in order, into its FileHashes.

FileHashes

A file’s content hash and the hash of each 64-KiB plaintext chunk, the last possibly shorter, from one read of its bytes: what an upload checks each chunk it sends against (§17.1, §17.9).

FileLocation

A stored file’s fixed location: the uploader, the stored object’s id and the file’s key. Equality compares the whole text, so another object or key is another location. Diagnostics never show the key.

FileRef

One file as its record stood when it was read.

FileUpload

One durable upload of one stored object; its plaintext chunk hashes are owned child rows. The location carries the path and key its staging fixed. Failures live in _coven_pending under the object’s subject, not here.

FolderCopy

One copy a call to make files device-only writes (§17.3): its path, the temporary name in the same folder its bytes are written under, and the folders the call makes on its path.

FunctionArguments

The arguments SQLite passes one call of an app function. Only the arguments: the connection running the statement stays coven’s.

HeaderEvidence

A write’s signed header and every part root, retained from receipt or a loaded snapshot (D9).

InFlight

The stored objects this process is transferring one way. The worker transferring them adds each attempt as it starts and removes it as it ends, saying how, cancelled included. Clones share it.

IncomingSlot

An authenticated slot whose floor check completed before installation.

InputBudget

Retained encrypted bytes have a maintained total and explicit eviction count.

Journal

The journal inside one write, for sync’s steps.

LiveQuery

A subscription’s results and lifetime; dropping it ends future runs. Its results fail with E, the query closure’s own error type.

LiveQueryClosed

The query was dropped before its request could be replaced.

LiveQueryRequests

Shared access to replacing a live query’s request.

LiveQueryRevision

A request revision assigned by one live query.

LiveQueryRuns

How often a live query had run when asked, for tests and benchmarks that measure how many of its runs writes caused, and how many found nothing new.

LoadedSnapshot

Files retained by a loaded snapshot.

LocalBytes

What a store keeps on this device, in bytes on disk (§17.8, §19.3).

LocalBytesWatch

The measurements of what the store keeps on this device, as they change.

LocalEvidence

What this device knows locally about a file it uploads (§17.6): the upload, where its bytes go, its move, and the records about each.

LocalFileStream

An open local file checked against its recorded facts. Retaining it keeps the opened bytes readable across its upload completing and file unlinking, and prevents store deletion until its reads and handles have finished.

LostCell

One retained value and the write that set it.

LostValue

One durable lost cell or removed row.

MemberInfo

A live member and every device they registered (E9).

Migration

One numbered change to the app’s database, with its declared kind. Clones retain the same callbacks across bootstrap and database opening.

MigrationContext

App SQL inside the transaction owned by the migration run. The context borrows its owner and cannot change the transaction or connection.

MigrationOutcome

The classification of a migration committed by this open.

MoveId

One move’s identity on this device, never reused (§17.3, E3).

Namespace

A kind of file with its cache budget, declared when the store opens (§17.1, §17.8, E1).

NamespaceBytes

One namespace’s cache, in bytes on disk.

NewOperation

The initial state committed before any external effect.

ObjectRemoval

An object to delete from storage once after has passed.

OperationId

The local, never reused identity of an operation.

OperationRecord

A journal row read as one committed value.

OperationUpdate

A step transition, guarded against stale callers.

PinProgress

Verified cache coverage of requested files (§17.8, E8).

PinRequest

One file this device keeps whole as a switch asked.

PreparedDeviceOnly

Cloud files downloaded to copies in the person’s folder, ready for one write to make them device-only here (§17.3, E8). It holds nothing close waits for. Committed by no write, its copies stay reserved while it is held, and the next write or open removes them once it drops; abandon removes them at once.

PreparedPin

Files ready to pin in one write (§17.8). It holds nothing close waits for. Dropped uncommitted, or after the store closes, its copies’ names go free, and the next write or open removes their bytes.

PreparedUploads

A captured queue prefix whose writes all have their first-attempt keys fixed, in queue order. Only crate::Database::prepare_uploads makes one, and crate::Database::read_uploads reads its writes’ plaintext.

PreparedUserFile

An original read whole once before entering a write: its path, size and modification time, and the content hash and chunk hashes of the bytes that read found, which coven records and checks the original against.

ProviderAccess

A request makes confirmation unknown until the provider supplies evidence.

ProviderAccessChange

One account’s intention derived from membership and this device’s invitations.

ProviderAccessRequest

A request remains associated with its account until confirmation matches intention.

RaiseCapture

A breaking raise’s fixed original prefix and current counted coverage.

Read

A read that starts when polled and retains its store borrow until it ends, on the store’s writer or a read-only handle.

ReconfigurableLiveQuery

A subscription whose request may be replaced while it runs. Its results fail with E, the query closure’s own error type.

ReconfigurableLiveQueryEvent

One result with the exact request and revision that produced it.

RetainedBytes

Independent cursor over one pinned input. Closing the database invalidates every cursor; an absent cached range returns an I/O error, never a network read.

RetainedInput

One observed object version. A replacement invalidates the preceding handle.

RetainedRange

Encrypted bytes received for one provider observation; completion is separate.

RetryState

What decides the person’s retry, as coven_retry_effect holds it.

RetryWait

A persisted wait: T and W, and the consecutive unsuccessful attempts that chose W, so reopening does not reset the backoff exponent.

Row

A single result row of a query.

RowChange

One row change of a waiting write (E13).

RowKey

The primary-key values of a row, in the table’s declared key order (api.md).

Slot

A positive position in the store’s shared sequence (§5). Slot 0 names nothing: a prefix applied through 0 has applied no slot, and that count stays a plain u64.

SnapshotReload

Complete checked input for an atomic reload. Sync derives the administrative projection from the original signed history carried by the store snapshot and retained slots. Each readable audience reaches target before commit.

SnapshotStaging

One snapshot’s staging, from its first batch to the load or file check that reads its records, or the discard that removes them (§16.2). It is the one holder of what it stages for that whole operation: its steps are its phases, and the load takes it whole. Dropped while still holding records, as by a cancelled or panicking caller, it removes them.

SqlContext

App SQL inside one local write, and coven’s steps beside it (§4). Returning an error rolls back every statement and step. This borrowed context cannot change the transaction or access coven’s tables.

SqlFunctions

The app’s collations and scalar functions. Coven registers every one on each connection it opens to the store’s database, before any app SQL runs there: the writer, which also migrates, applies other devices’ writes and merges, the readers, and every connection of a read-only handle.

SqlReadContext

SQL access to one read-only snapshot. The connection and internal tables remain private; even SQL with RETURNING cannot write through this context.

SqliteSettings

SQLite settings for every connection coven opens to the store’s database: the writer and the readers of a writable handle, and every connection of a read-only one. A setting left None keeps SQLite’s own default, except checkpoint_fullfsync on macOS and iOS, which coven turns on, and auto_vacuum, which is Incremental. Coven applies them as each connection opens, before any of its own statements.

SqliteSettingsInEffect

The SQLite settings one connection to the store’s database has in effect, as SQLite reports them. Every connection has the same, except that a writable handle’s writer never checkpoints as it commits.

StagedDigest

A digest of one staging’s records as its tables hold them. Staging is a function of the snapshot’s bytes, so two stagings of the same snapshot hold the same records, and differ only where this device’s disk changed one (§19.1).

StagedFiles

App bytes stage_files wrote to coven’s copies of them, under names reserved in this store, with what its batch returned, until a write puts them in rows (§17.2). It holds nothing close waits for. Dropped uncommitted, or after the store closes, its names go free, and the next write or open removes the bytes.

StoreCircle

A circle and its current membership; deleted circles retain their name. Its keys come from received introductions, not this membership projection (§12.1).

StoreDevice

One install, retained after removal or replacement so its older objects remain attributable (§10.4).

StoreIdentity

A store’s identity and current name (§10).

StoreMember

A member in the applied prefix, keyed by stable id in StoreState::members.

StoreState

Store state, including removed identities needed to check older writes (§10.4).

StoreVersion

A selected version raise and the snapshot it chose (§18.3).

SyncFacts

What the sync state is computed from, in one committed snapshot.

SyncStatusRow

coven_sync_status’s row as it is read.

SyncedTable

A synced table’s key, audience, file references, shared triggers and whether only each row’s original creator writes it directly (E2).

TransferMeter

Tells one attempt how far it has got. Once the attempt ends, it tells nothing: a request still finishing can’t move a later attempt.

TransferProgress

How far one transfer has got: the bytes of its encrypted object handed to the connection or received, in whatever order, out of the object’s whole size. Known from the transfer’s start; never stored.

TransferWatch

Hears how far each file in flight one way has got. Changes that arrive faster than the reader reads are heard together: the next read names each file that differs from what the reader last heard, and how each one it heard in flight ended.

Transferring

One attempt to transfer a stored object. Its worker ends it as its transfer ended; dropping it otherwise, as a cancelled attempt does, ends it as dropped.

UnsentWork

What this device committed and has not uploaded: writes and files (E1).

UploadBytes

An incremental SQLite BLOB reader. It never collects the waiting write.

UploadFacts

One upload in the queue, as the sync state reads it.

UploadParts

Audience stream descriptors paired with their bounded plaintext readers.

UploadPlaintext

A waiting write’s plaintext, fixed at commit, read under one committed reader transaction.

UploadProgress

Bytes the provider confirmed in a recorded upload session. Sending bytes alone does not advance it.

UploadQueueState

The queue as the app observes it: the pause setting and every queued file with its recorded session, from one committed state, and the files this process is sending as it was read (E7).

UserFile

The facts recorded for the user’s original, which coven never changes.

WaitingUpload

A captured write ready to seal. Sealing and transport belong to sync; these are its input streams and the keys it seals with.

WriteAuthorship

A write’s signed header and part roots, and the hashers that check each opened part against its root (D9, D11). The database checks the roots; sync checks the header signature with the rest of the object.

WriteBatch

App bytes to stage, before the write that puts them in rows; a failure discards all of them. Each staged file gets a new id from the store’s id source, which the batch borrows while the app stages; the write’s SQL puts the id in the rows that reference the file.

WriteId

One device’s numbered write (§4).

Writers

The other devices that can still write: every device besides this one not gone for good (§14.1), each with the slot whose entry added it, when known. Stored files (§17.10) and kept records (§16.7) wait for the same devices.

Enums

AnalysisLimit

How many rows of each index ANALYZE reads.

ApplyOutcome

Applying a previously applied write never runs it again.

AutoVacuum

What happens to the pages deleted content frees.

Binding

When a write setting a file reference goes out (§17.4, E2).

Boundary

A checked raise/reset and the snapshot named by that entry. Its selection is derived from kept entries, independently of whether coverage has been read.

CacheSize

A page cache’s size, which SQLite counts in pages or in kibibytes.

CacheSpill

Whether a transaction may spill changed pages before it commits.

ChangeOp

The operation a waiting write performs on a row.

CheckpointMode

SQLite’s checkpoint modes (PRAGMA wal_checkpoint).

ClaimRead

Authenticated observations supplied by the sync reader.

ClaimSettlement

Settlement of the most recent attempt.

ClaimWork

The original work carried by a claim. Every slot kind shares one counter.

CovenMigrationError

Coven’s local tables cannot be used at this version (Appendix C.1, E1).

DbError

A failed database call or a write the database refuses (§4, §9, §15, §17).

Determinism

Whether a scalar function’s result depends on its arguments alone.

DeviceState

What counted administrative slots did to a device id (E9). Later slots from a removed or replaced device are refused (§14.1, D6).

DeviceStop

Why a device stopped for good (§14.1, §19.3).

DownloadedPartStream

Whether sync could decrypt the corresponding part in the header.

EntryTarget

The target a proposed change can no longer affect.

FileEvidence

What checked retained bytes establish about the uploaded files they name (§17.10).

FilePlace

Where a file is (§17.2): in storage, or only on one device.

FileSource

An owned buffer or a reader whose stream coven consumes exactly once.

FileWork

Which of this device’s work on a file’s stored bytes a record is about.

IncrementalVacuum

How many free pages an incremental vacuum gives back.

JournalSizeLimit

How large the WAL file may stay after a checkpoint resets it.

LiveQueryCause

Why this run was requested; the first run answers the initial request.

LoadStep

A step of loading a store from storage (§13.4), in the order they run. A step runs only when it has work to do.

LocalFileError

A local file operation’s typed failure.

Lost

Values retained when a cell loses or a row is removed.

MigrationChange

How one migration changed the schema and synced rows (§18.1).

MigrationError

The application migration run could not complete.

MoveFile

A file of this device, on it only, to move to the cloud (§17.3, E3).

OldWrites

What a breaking migration does with received late old-version writes.

OpenError

Opening the database failed: its writer or read-only connections, its lock, its settings or its migrations (§4, E1, E13).

OpenStep

A step of opening a store for writing (§4), in the order they run. A step runs only when it has work to do, so most opens report none.

OperationOutcome

How an operation an app’s write journaled ended (§11.4): coven_operations.outcome holds it from the transaction that ends the operation’s journal row until a write acknowledges it, so an outcome nobody awaited is still there to read.

OperationRejection

Why the current applied state refuses an administrative operation.

PageSize

A database page size: a power of two from 512 bytes to 64 KiB.

Place

Where a staged file is to be: on this device only, or uploaded to the cloud (§17.3).

PrerequisiteRows

Committed state a waiting operation names.

Provenance

A namespace’s kind: whose bytes its files are (§17.1).

ReadOnly

A read-only handle: it reads synced rows and keeps its own file cache, and nothing else (E1).

RecordedLocation

Whether a storage location is recorded on this device, and whether this device holds credentials for it (§19.1), with the location’s provider. The database keeps the provider as the name sync gives it.

RemovalRule

A rule responsible for a removed row.

Replacement

The write, rules, breaking schema version, dropped data or refused permission responsible for a loss.

RetrySubject

The work a persisted wait delays.

RetrySync

Whether a started connection will plan.

RowAuthorizationFailure

Why a member’s row change was refused (§9.6).

RowIdentity

How independently inserted rows choose their identity (§9.2).

SchemaError

A schema rule checked on open and after migrating (§9, §15.1).

SecureDelete

Whether deleted content is overwritten.

SlotContent

One slot kind; readable write parts are applied together.

SnapshotError

Snapshots or their gap writes could not be loaded into this database.

SnapshotSource

One readable audience’s starting prefix.

SnapshotWriteError

A snapshot failed to read, encode or reach its plaintext consumer.

SqliteError

Enum listing possible errors from rusqlite.

StagedDamage

Damage a test makes to a staging, as damage on this device’s disk would (§19.1).

TempStore

Where temporary tables and indices are kept.

TemporaryDirectoryError

Why the folder for temporary tables could not be named (E1).

TransferChange

A change to one file’s progress, or every file’s.

TransferEnd

How a file’s transfer ended, decided in the step that takes it out of the files in flight. When two attempts move one file at once, the last to end says it.

UndoCause

Why an operation was undone (§11.6).

UnprovenFiles

Why retained bytes cannot yet name every file they refer to (§17.10).

UploadCompletion

What an upload’s completion did (§17.3, §17.9).

UploadReadError

A queue read failed in the database or in its consumer.

WalAutocheckpoint

When coven checkpoints the WAL by itself.

WalCheckpoint

What a checkpoint did, as SQLite reports it.

WriteCutoff

Why a lower slot permanently excludes an original write.

WriteWait

A prerequisite for applying a downloaded write.

Writer

The store’s one writer: it writes, migrates, transfers files and keeps their records (§4).

Constants

BOUND_FILE_LIMIT

The size limit of a bound reference that declares none: 1.5 MiB (§17.4).

REQUEST_FIXED_STEP

The step a provider-access operation reaches once its request’s target is fixed, before storage is called.

Traits

Authorship

What a loader needs from sync to authenticate another member’s write.

FileLocationKey

Crate-to-crate access to a stored file’s key, for coven’s owners; not re-exported by the app API.

Mode

The mode a store’s handle opened in: Writer or ReadOnly.

Params

Trait used for sets of parameter passed into SQL statements/queries.

PendingValue

Sync supplies its complete typed record; the database owns its atomic lifetime. The associated subject is the stable key, independent of the reason.

SqlRead

Ordinary SQL reads through a read context or a write’s, so code that reads the same way inside a write and outside one is written once. Inside a write it sees the write’s own changes.

ToSql

A trait for types that can be converted into SQLite values. Returns crate::Error::ToSqlConversionFailure if the conversion fails.

WriteFailure

A caller’s write error can retain both its original cause and failures that happen while rolling back or removing bytes, and says which bug it carries, for a write whose caller stopped waiting (E15). A write fails with its closure’s own error type, which implements this: DbError for ordinary database clients, sync’s error for sync’s writes, and an app’s own type for the app’s writes through the facade (E3).

Functions

closed_sync_facts

What a closed store’s sync state is computed from, and its unsent work, in one committed snapshot of its database, read through a connection of its own while lock, the store’s writer lock, shows that no handle has it open (api.md E1, E5). It reads only coven’s tables, so the app’s declarations aren’t needed; coven’s tables must be at this coven’s version, as a read-only open requires. Nothing is sent or downloaded and no network is watched, as for a read-only handle. A caller that stops waiting leaves the read to finish, and its panic goes to the store’s bug sink (E15).

discarded_operations

The operation journal of a database a device reset discarded (§19.3), read in place and read-only on a blocking thread, never opened as a store. A journal SQLite reports damaged, or whose records don’t decode, is DamagedDatabase. Like read_store_name, it reads only coven’s table and needs none of the app’s collations or functions. A caller that stops waiting leaves the read to finish, and its panic goes to bugs (E15).

discarded_store_name

The local creation name in a reset’s discarded database. The reset owner holds its directory lease while reading this setting. Like read_store_name, it reads only _coven_store_state and needs none of the app’s collations or functions. A caller that stops waiting leaves the read to finish, and its panic goes to bugs (E15).

prepare_user_file

Read a user’s original once, recording its whole-file hash and each upload chunk’s hash from the same bytes, and reporting total bytes read. Changes during the read are refused; later ones fail its upload, whether it is staged for the cloud or moved there later.

read_store_name

Read the name for a local store listing without migrations or a writer. It reads only coven’s _coven_store_state, and SQLite looks a collation or function up only for a statement that uses it, so the app’s aren’t needed. A caller that stops waiting leaves the read to finish, and its panic goes to the store’s bug sink (E15).

set_temporary_directory

Keep SQLite’s temporary tables in directory, for every store this process opens from now on. Call it before opening any store.

sqlite_error_is_disk

Whether SQLite failed because of the disk under it: full, failing, gone read-only, or damaged.

stored_time

The time a stored count of milliseconds since the Unix epoch names, as coven_retry_effect.cooling_until and coven_sync_status.last_synced hold it. One the clock can’t name is DamagedDatabase (§19.3).

unix_seconds_and_nanos

A time as coven_user_files lists a modification time, in modified_seconds and modified_nanos: whole seconds since the Unix epoch, rounded down, and the nanoseconds past that second, from 0 through 999,999,999 (§17.3). Half a second before the epoch is (-1, 500,000,000). An app compares a file’s time on disk with the view’s through it.

Type Aliases

SqliteResult

A typedef of the result returned by many methods.