Expand description
The shared store sequence, durable operations, snapshots and file transfers.
Structs§
- AddDevice
- A pairing
add_devicemade: what the screen that adds a device shows. - AddDevice
Id - A pairing’s UUID, which names its request’s path in an invite’s place (§13.2, format.md D10).
- AddDevice
Request - A checked pairing request, as
AddDeviceStatusshows it (§13.2). - Approval
Waits - The wait between an approval’s checks, which a join and a pairing keep: its persisted delay, armed again after reopening, and any provider cooldown (§6.7).
- Circle
- A circle the local member belongs to (E12).
- Circle
Member Info - An active store member in a circle (E12).
- Circle
Terms - What the app says of the circle its joining person’s request makes: the admission will make it, with the person as its only member (§13.2).
- Code
Metadata - Store, member and provider facts shared by every code kind.
- Connection
Coming - A connection attempt’s mark on the file layer’s storage: while it lives, a connection is coming (§17.7).
- Creation
- What slot 1 sets up: the store, its first admin with her join facts, her
first device, the first store key and the circles’ first keys
ringholds. - Credential
Keychains - The keychain entries a credential change commits: this device’s provider credentials, and the person’s restore code and S3 key, saved for their next devices (§13.1).
- Credential
Rollback - Previous values of exactly the custody entries a credential commit changes. Setup and bootstrap retain this until their whole operation has committed.
- Damaged
Object - An object whose checks failed (§19.1).
- Detection
Record - One detection run’s record, as committed.
- Device
Credentials - This installation’s committed storage credentials. Every write of them
goes through
Self::write, so a refresh commits its replacement only while custody still holds the tokens the provider rejected. - Device
Info - One of a member’s device ids in the committed prefix (E9).
- File
Range Stream - A borrowed stream of bounded authenticated plaintext buffers.
- File
Stream - An open file. A file never changes its bytes, so nothing later changes what it reads. Its shared store lock prevents deletion until the stream and its I/O finish, including reads still running after the store closes or the caller cancels.
- Files
- Owns storage, database file operations and the device’s file area
(Appendix F.3), for the store’s writer or a read-only handle
(
Files<ReadOnly>), which only reads files and keeps its cache. The writer’s starts one commit-driven worker, for uploads and pins; no sync loop or timer is created. Callclosebefore closing the database. - Held
Intervals - What the guards hold, as the owner of a wait reads it.
- Holder
Device - An active device of a
KeyHolder. - Invite
- One of this device’s open invites (§13.2).
- Invite
Expiry - Ends this device’s invites as their lifetimes end, from the store’s opening until its handle closes. Dropping it stops the wakes too. A panic in it goes to the store’s bug sink and ends the wakes, as does a bug a write returns; the next open writes the expiries that passed.
- Invite
Info - What an invite code tells before connecting: as typed or scanned, and as a join under way saved it (§13.2).
- Join
Poll - An approval’s wait for its next poll: its persisted delay, armed again after reopening, any provider cooldown (§6.7), and the intervals the app holds (§13.2).
- Join
Request - A checked request, presented with the account from its local invitation.
- Joining
Identity - An unpublished member identity and its immutable request. The member id is the one the invite fixes; the keys are this device’s fresh pair. The only durable local copy is encrypted with the invite secret, bound to the complete code. No member keys or provider credentials enter final custody while waiting. One join holds it, from preparing or resuming the request until the join ends.
- KeyHolder
- A member of the store that holds a key a stopped device waits for: a copy of the key is sealed to the member’s current sealing key, so every device of the member with that pair opens it, and a device of the member that reads the key’s audience sends the copy on its next pass (§12.1).
- Member
Info - A live member and every device they registered (E9).
- Network
Follow - Follows one open store’s network watch from opening to closing: built as the store opens, already showing what the platform says, and closed before the database. It keeps the watch, whose platform registration ends with it.
- NewCircle
- A circle slot 1 makes, whose first key
ringholds. - NewInvite
- What the app asks an invite for: whom it admits, how they reach storage, and how long it stays open (§13.2).
- Operation
Id - The local, never reused identity of an operation.
- Operation
Steps - The steps of the app’s write that journal an operation (§4, §11.1): checked against the state this device has applied, journaled with or without storage, and run by a later pass. One per writer handle.
- Pairing
Ask - A request for a pairing and the pair it asks with.
- Pairing
Info - What a pairing code tells before connecting (§13.2).
- Parks
- The parks of one loop.
- Pass
Requests - Requests a pass took when it began, answered when it ends. A pass that panicked, or was dropped, before answering them leaves them waiting again, for its owner’s ending to answer.
- Pending
Record - One local first unmet condition, identified by its subject (§19.1, E5).
- PinProgress
- Verified cache coverage of requested files (§17.8, E8).
- Provider
Check Permit - A provider check’s object while permitted (
SequenceState::permit_provider_check): removes it when dropped, a dropped future included. - Queued
Upload - One queued upload: what it is doing, and its committed progress.
- Read
Progress - Where a read that fetches from storage tells how much of its range is here: the count of the range’s bytes in hand, cached or received, each time it grows while the read fetches. A read this device serves alone, from its own copy or the cache, tells it nothing (§17.7).
- Recorded
Invite - An invite a test records outside a store, as
make_invitejournals one and later steps advance it (api.md E4): its id, the member it fixes, and its stage. - Restore
Codes - Owns code generation and credential changes for one open handle, for its whole lifetime: connected or not, one change runs at a time, and a read waits for the change in flight. A change that needs the connection takes its sequence owner as an argument. Closing waits for updates holding the lock, even when their app futures were dropped.
- Retry
Answer - Resolves when the first sync pass after a retry request ends (E5). Dropping it leaves the retry in place.
- Retry
Waits - One installation’s retry schedule. Construct when the store opens and inject the same owner into operations, file transfers, the sync loop and every provider connection.
- Saved
Name - The store’s name as this device has it, and the slot that set it: 1 for creation, otherwise the rename’s. Of two names, the later slot’s is newer.
- Sequence
State - Shared state of this open installation. It carries no time-based permission.
- Sequence
Sync - Owns sequence progress. App commits use the database independently; every publisher shares this owner’s serialization and actual blocked state.
- Session
Sign In - A sign-in held for this session only, until setup or bootstrap publishes it to device custody: with the store, or for a join once it saves its invite code. It then refreshes there (§13.2, §20.2).
- Setup
Journal - One storage setup’s journal row, as its owner last committed it.
- Sync
Loop - Control of one serialized pass loop. Commands survive caller cancellation.
It publishes its activity to the owner’s
SequenceState. - Sync
Often - The intervals apps hold, each with how many guards hold it.
- Sync
Often Guard - An app’s request for idle passes at most its interval apart. The request lasts until the guard drops; the shortest interval held wins.
- Sync
Status - What a status screen shows (E5, §19.1): the sync state and when sync
last finished, as
coven_sync_stateshows them andsync_status()reads them. - Transfer
Limits - Limits shared by the open store’s transfer consumers (E5).
- Upload
Progress - Bytes the provider confirmed in a recorded upload session. Sending bytes alone does not advance it.
- Upload
Queue - Observable upload queue state (E7): one committed snapshot of the queue, with the uploads this process is sending as it is read.
- Upload
Settings - The writer’s copies of the upload settings, and the connections its upload runs’ attempts use.
Enums§
- AddDevice
End - How a pairing ended (§13.2).
- AddDevice
Status - Where a pairing is (§13.2). The app offers approving and declining only
for a request that is
Waiting, and ends the pairing when its screen closes, whatever its status. - Change
Outcome - How an admin change an app’s write journaled ended, for the kinds
RenameStore,SetRole,RemoveMember,RemoveDevice,RenameCircle,DeleteCircle,AddCircleMember,RemoveCircleMemberandApproveJoin(§11.4):coven_operations.outcomeholds 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. - Code
Error - A malformed code or one intended for the other operation.
- Code
Info - Code metadata safe for presentation before opening the store.
- Code
Kind - The three codes that can open a store on a new device.
- Connection
Retry - What permits this connection to attempt another pass. Time is held by
RetryWaits. A failure that waits for something other than time holds every pass, and keeps what the status showed for it. - CutOff
Refusal - Why
confirm_device_cut_offrefused (§14.2, §20.9). Each is a reason the call can’t change anything; the app tells the person which one. - Device
IdEvidence - Authenticated evidence that another installation uses this device id.
- Device
Only Error - Why no file of a call was made device-only (E8). Whatever the call made is removed before it returns, or, if removing it failed too, at the next open.
- Device
Only Step - A step of preparing files to be made device-only (§17.3, E8), which a
host draws a bar for: one step for each file downloaded, in order. Done
and total count the file’s bytes; done plus
before, out ofall, is how far the whole call has come. - Device
State - What counted administrative slots did to a device id (E9). Later slots from a removed or replaced device are refused (§14.1, D6).
- Device
Stop - Why a device stopped for good (§14.1, §19.3).
- Drain
Outcome - Result of an app retry (
retry_uploads_now), or of one upload run. Individual failures stay inpending(). - Entry
Target - The target a proposed change can no longer affect.
- File
Missing Reason - Why a file can’t be read (§17.6).
- File
Read Error - Reading a file failed with a cause the app can distinguish (E8).
- File
Source Failure - The staging device cannot supply the file’s original bytes.
- File
Status - A file’s current availability (E8).
- Fresh
Change Outcome - How an admin change an app’s write journaled ended, for the kinds
CreateCircleandReplaceMemberKeys, ascoven_operations.outcomeholds it (§11.4). Each names something no applied state holds yet, a new circle or a member’s new pair, so it is never satisfied: a state that already holds it refuses it (§12.3, §15.5). - Invite
Access - How the invited person reaches the store’s provider.
- Invite
Admits - Who an invite code admits, fixed when the admin makes it (§13.2, §13.3):
the byte the code carries. It decides which person a join request may name
(
objects::Joiner); the joining device reads it from the decoded code. - Invite
Lifetime - How long an invite stays open after it is made, by the inviting device’s clock (§13.2).
- Invite
Outcome - How an invite ended, the kind
Invite, ascoven_operations.outcomeholds it (§11.4, §13.2):coven_operationslists an invite only once a sharing refusal ends it. Its approval’s binding is an operation of its own, of the kindApproveJoin. - Invite
Stage - Where one of this device’s open invites is (§13.2).
- Join
Outcome - The joining member’s outcome after checking storage (§13.2).
- Joiner
- Who asks to join through an invite (§13.2): one of two, as the invite admits. A member’s own new device asks through an add-device pairing instead, which the format’s request can say and an invite never takes.
- Last
Pass - How the last pass that reached storage, or failed trying, ended (E5), as
coven_sync_status.last_passholds it. It outlives each connection: opening keeps it, and the running loop writes it as each pass ends. An error is kept as its text, which names every cause below it with secrets and URLs already cut, so a pass read after the process that ran it ended still says why. - Listed
Outcome - An outcome as a write keeps it in
coven_operations.outcome, in the outcome type of the kind the operation is listed under. The column holds the inner outcome, so each type reads its own kinds’ rows. - Local
Failure - A local invariant or resource failure; immediate calls retain the native cause.
- Network
Owner - An owner of waits that acts on reports.
- Operation
Kind - The purpose of an unfinished operation, including maintenance.
- Operation
Rejection - Why the current applied state refuses an administrative operation.
- Pairing
Check - What a check of the request’s path finds.
- Pass
Failure - Why a pass, or the connection attempt that begins one, failed: how it
ended (
LastPass, E5). - Pending
Reason - A typed current condition, never an error’s display string.
- Pending
Subject - Stable identities of work, independent of attempts and wall-clock time.
- Prerequisite
- A fact required before processing can continue.
- Provider
Access Action - The provider’s intended sharing change.
- Recorded
Invite Stage - Where an invite a test records is, as
coven_invites.stagenames it. - Recorded
Joiner - Who asks in the request of an invite a test records.
- Refusal
- One vocabulary for refused objects. Native causes survive immediate calls; persisted records retain only the variant. Equality ignores causes.
- Removal
- Why a device is not in the store, and won’t be again (§13.2, §14.1).
- Required
Update - The software version required to decode or apply an input from storage: the app schema its writes use, or the object format it is encoded in. Sync, setup and unlock all report it, so it lives with the formats.
- Reset
Reason - Why this installation can’t send under its keys or id, as
NeedsResetnames it (§19.3, §12.3). - Retry
- What can permit another attempt; no attempt count determines it.
- Retry
Effect - What the person’s retry would do if made now (E5), as
coven_retry_effectholds it: run a pass, or be answered at once without one. An app offers a retry only while it isPass; the status says why it is not. - Retry
Outcome - What the first sync pass after the person’s retry came to (E5).
- Sequence
Status - Current sync activity. Reaching the read end says nothing about pending files.
- Status
Failure - What stopped a pass as a whole, as
LastPasskeeps it: aSyncFailurewithout the error objects, whose text it holds beside it (E5). - Storage
Setup Outcome - How a storage setup ended, the kind
StorageSetup, ascoven_operations.outcomeholds it (§11.4, §11.6). - Sync
Activity - What Syncing is doing, as
Syncingnames it (§19.1): the first of what the running pass moved last, a bound file moving or next in line, a write next in line, and the next pass’s turn. - Sync
Cause - What names a state: the last pass, or the first pending record, in the
order they arose, that names it, with the cause
coven_pendingkeeps. - Sync
Error - A synchronization request failed; its durable queue, if any, remains retryable.
- Sync
Failure - A sync step stopped as a whole (E5).
- Sync
State - The sync state (§19.1). With several candidates, the first of
Removed,NeedsReset,UpdateNeeded,SignedOut,NoAccess,FolderMissing,ClockWrong,StorageFull,OfflineWithUnsentChanges,Offline,Failed,Syncing,WaitingToSync,Syncedshows;NotSyncedcomes before them all.coven_sync_state.detailholds it as JSON, which this type reads. - Sync
Wait - What waiting to sync waits for, as
WaitingToSyncnames it: what holds every transfer, the pass’s and each file’s alike, first; then, for a bound file waiting in the upload queue, what holds that file, then a write’s own key (§19.1). - Undo
Cause - Why an operation was undone (§11.6).
- Unreadable
Saved Code - Why a saved entry can’t be restored from. Listing shows it, with its store id, so the person can forget it (§13.1).
- Upload
Phase - What a queued upload is doing, bound and trailing alike: the sync state names bound files only, so what a trailing file waits for, and its failure, are shown here (§17.9, §19.1). Whether it is sending is persisted nowhere: a reopened store starts with every file waiting.
- Upload
Wait - What a queued upload waits for, the first that holds (§17.9).
- Write
Cutoff - Why a lower slot permanently excludes an original write.
Traits§
- Files
Mode - What a handle’s mode adds to its file owner: the writer’s upload
settings, which the upload runs and the app’s setting changes use, and
nothing for a read-only handle, which runs no upload. Sealed with
Mode.
Functions§
- admitting
- The admission of
memberwithkeysthat a join request would make, for a test that admits a member without a join: the circle it makes, namedname, and the member’s own copy of its key. - change_
operation - The journal row of
changeas the app’s write journals it, and the kindcoven_operationslists it under, for a test that journals it outside a store (api.md E4). - commit_
credentials - Commit device credentials and, on Apple, the separate S3 key. Setup and bootstrap also supply the restore code with the store’s name, and remove any S3 entry when setting up an account provider. Replacing credentials supplies no code; OAuth refresh touches neither person entry. A failed write restores every prior value and returns any rollback failures with the original cause.
- connection_
failure - The last attempt is offline only when its network failure received no reply.
- decide_
creation - Seal slot 1, journal its exact bytes as this device’s attempt at it with
the operation that sends it, and apply it, all in
database. The store is not published yet, so no other device can claim slot 1 first; setup later sends these bytes (§10.3). The creator’s copy of each key slot 1 introduces rides in its clear prefix, as an admission’s copies do (§12.1). Applying slot 1 runs the app’s joining write for the creator’s device, as an admission’s application does for a joiner’s (§13.2). - decode_
code_ info - Decode and validate the complete code before returning public metadata.
- decode_
invite_ info - What an invite code tells, read before any sign-in: the app signs in with
its
metadata.oauth_access, then callsjoin_with_invite. Refuses the code as that call would:WrongKindfor a restore or pairing code,Invalidfor one that doesn’t decode. - decode_
pairing_ info - What a pairing code tells, read before any sign-in: the app signs in with
its
metadata.oauth_access, then callsjoin_with_pairing. Refuses the code as that call would:WrongKindfor a restore or invite code,Invalidfor one that doesn’t decode. - decode_
restore_ info - A restore code’s metadata, or
WrongKindfor an invite or pairing code andInvalidfor one that doesn’t decode. - ended_
for - Whether the request kept for
codewas recorded as ended (record_ending). - follow_
name - Rewrite the entry’s name when
nameis newer, keeping the code the entry holds: only setup, joining, restoring, resetting and member-key replacement save a code over a readable one (§13.1). An absent entry stays absent, so a forgotten entry stays forgotten. - invite_
operation - The journal row of
invite, asmake_invitejournals an invite and later steps record its state: the invite made by device 1 for an account, with a fixed secret and an expiry in 2096, and the request as coven-format’s fixture request withinvite’s id, member and joiner (api.md E4). - location_
code - The restore code that names
identity’s held pair and the store’slocation, with no credentials (§13.1). - pairing_
status - The status of
pairing, fromrecords, the journal’s pairing rows (operation_kind::PAIRING), which a one-shot read or a live query reads.Nonefor a pairing this device never made or has forgotten (E10). - pairings_
opened - Opening the store ends every pairing a closed handle or a crash left: no screen shows one now. Each is forgotten once its marker is in place, and one that had ended already is forgotten at once, all in one transaction (§13.2).
- read_
connection - Read the saved provider location and custody credentials without opening a database. Shared by normal sync, read-only file access and damaged-database recovery. Absence means storage is not configured on this installation.
- read_
invite_ code - Decode an invitation for the joining side after validating provider admission.
- read_
location - The storage location recorded on this installation, with its labels, and whether custody holds credentials for it, as the sync state reads it (§19.1): as a store opens, and as its closed status is read (api.md E1).
- read_
pairing_ code - Decode a pairing code for the new device after validating provider admission.
- read_
restore_ code - Decode a restore code for bootstrap, preserving a valid wrong-kind distinction. Its storage part has already been validated.
- read_
saved_ code - Read a saved entry for
store, and its code’s location. - record_
connected_ outside_ store - Write that
locationis recorded onconnection, a test’s connection outside any store, with this device holding its credentials, asrecord_openedwrites it. - record_
ending - Record that the join with
codeends without a store, before anything it kept is deleted: a call that stops part way through the deletion finds the record and finishes it without connecting. Nothing saved is nothing to record. - record_
location - Write whether a storage location is recorded here and its credentials
held, with the location and its labels, as setup, a change of
credentials, a connection’s new label or releasing a connection finds
it;
finished, for setup, is when it read the store to its end. A failure fails the store’s handle with its cause. - record_
opened - Write, as the store opens, whether a storage location is recorded here
and its credentials held, with the location and its labels, and that no
pass moves;
finished, for a store joining or restoring read to its end, is when (E5). A failure fails the store’s handle with its cause. - registration_
journaled - Whether this installation’s registration is journaled and has not ended: its claim may still land, or has landed and not yet been applied. A restore that ends without its store, its device absent from the history it applied, reads this before it removes its installation (§13.1, §11.6).
- removal_
journaled - Whether this installation’s removal of
device, its own, is journaled and has not ended: its claim may still land, or has landed and not yet been applied. A deletion that leaves the store reads this to learn whether it has passed its point of no return (E1, §11.6). - replacement_
code - The code a device with the store open saves in place of an unreadable
entry (§13.1), or
Nonewhen it holds no current code: the store has no location or identity, custody holds no member pair, the member was removed, or another device replaced the keys this device holds. - restore_
sign_ in - The sign-in a restore of
storein place fromcodeneeds,Noneon S3 and CloudKit, read before any sign-in: the app signs in with it, then callsCovenBuilder::restore_device. Refuses the code as that call would:WrongKindfor an invite or pairing code,WrongStorefor another store’s restore code,Invalidfor one that doesn’t decode. - sealed_
join_ request - The request as it is stored at
path: sealed with the invite secret’s request key and signed by the pair it names (§13.2). - sync_
functions _coven_sync_stateand_coven_upload_phase, the functionscoven_sync_stateandcoven_upload_phasescall, for the database to register on every connection: the state and each upload’s phase computed in this crate’s Rust code, so that it stays the one definition the Lean model checks while an app’s screen reads them in SQL (§17.9, §19.1).- sync_
status - The sync state and when sync last finished, as
coven_sync_stateshows them in one committed snapshot (§19.1). - test_
joining_ circle - The circle a join request of
memberwith the sealing keysealingwould make instore, named “Circle” at base zero, for a test that seals a request itself.
Type Aliases§
- Operation
Error - An operation failure retains the same typed causes as an ordinary sync call.
- Storage
Commit - Credential and settings commit performed after remote setup has succeeded.
- Storage
Rollback - Compensation retained until setup has committed its keys and applied origin.