Struct SyncedTable 

pub struct SyncedTable { /* private fields */ }

A table that participates in changeset sync, declared at startup by the host and passed to [crate::CovenBuilder::synced_tables].

A plain SyncedTable::new table syncs unconditionally — every row goes to peers. SyncedTable::remote_root keeps that whole-table row sync and also makes the row a blob-locality root whose blobs are always Remote. SyncedTable::gated_by makes it a gated root: a boolean column whose truth decides, per row, whether that row (and its declared FK-descendants) is shared. A gated-false root and its subtree stay local; flipping the gate true re-emits the whole now-visible subtree to peers, and flipping it false again retracts that subtree from peers (emitting deletes for the rows leaving the shared set) while the rows stay local.

SyncedTable::gated_by_descendants is the upward complement: an always-shared ancestor that should sync only while at least one gated descendant survives. Without it, an album whose only releases are gated out would still sync its own row and land on peers as an orphan with zero children. A gated-by-descendants ancestor is cut exactly when its gated subtree is empty, and the keep composes recursively up the foreign-key chain (an artist syncs iff a surviving album references it, which syncs iff a surviving release does). The keep-children are inferred from the foreign-key graph, not declared — listing them by hand would restate the schema and drift the moment a new foreign key is added.

A table is either a remote root, a gated root, a gated-by-descendants ancestor, or plain — never two of these. See [super::gate] for the gating mechanics. Orthogonally, any table may carry a blob (SyncedTable::carries_blob): blob-bearing-ness is a property of the row’s columns, not of its gate role. A table may also be marked an asset (SyncedTable::asset): a decoration (a cover, an artist image) that rides its foreign-key subject’s gate but never keeps that subject alive. Asset-ness is likewise independent of the gate role.

Each table must have an id text primary key at column 0 and an _updated_at TEXT NOT NULL column (the HLC/LWW timestamp). Tables not in the set the host declares on the builder are local-only and never synced — that is also the mechanism for keeping device-local state (per-device pin/cache columns, local paths) out of sync: put it in a table you don’t declare. An empty set is rejected by [super::cycle::init_sync].

The required RowIdentity defines which ids may name rows. Use RowIdentity::IndependentUuid for independently created rows and RowIdentity::SharedKey only when equal application keys intentionally name and merge as the same row.

Implementations

impl SyncedTable

pub fn new(name: impl Into<String>, row_identity: RowIdentity) -> SyncedTable

An ungated synced table: every row syncs under the required identity mode.

pub fn gated_by(self, column: impl Into<String>) -> SyncedTable

Make this a gated root: rows sync iff the boolean column is true.

pub fn scoped_by(self, column: impl Into<String>) -> SyncedTable

Make this an audience root whose TEXT column selects Store, Local, or one committed circle for the row and its foreign-key descendants. A store with an audience root requires crate::HomeStorage::Opaque.

pub fn remote_root(self) -> SyncedTable

Make this a remote root: every row syncs, and blobs on the row or its foreign-key descendants are always Remote. There is no Local state for [crate::blob::transition::make_remote] or [crate::blob::transition::make_local] to transition.

pub fn gated_by_descendants(self) -> SyncedTable

Make this an always-shared ancestor kept alive by its gated subtree: a row syncs iff a surviving (kept) descendant row references it. The keep-children are inferred from the foreign-key graph at gate-build time, so there is nothing to pass here.

pub fn carries_blob(self, decl: BlobDecl) -> SyncedTable

Declare that rows of this table carry a blob, located by the columns in decl. coven derives the blob set itself from these columns + the live schema (see [crate::blob::decl::BlobDecls]); it never calls back to the host to discover blobs. Independent of the gate role.

pub fn asset(self) -> SyncedTable

Mark this table an asset of its FK subject: a host-provided decoration (a cover, an artist image) that rides its subject’s gate but never grants keep. The asset still inherits the gate as a child of its subject — it syncs exactly when the subject is kept — but the gate excludes it from the subject’s gated_by_descendants keep computation, so an asset row alone never keeps an otherwise-empty ancestor alive (and the asset-rides-subject vs. subject-kept-by-children relation can never form a cycle). Independent of the gate role; declare it on an FK child of the subject.

pub fn name(&self) -> &str

The table name.

pub fn row_identity(&self) -> RowIdentity

How this table’s ids name logical rows across devices.

pub fn gate_column(&self) -> Option<&str>

The gate column name, if this table is a gated root.

pub fn audience_column(&self) -> Option<&str>

The audience column name, if this table is a scoped root.

pub fn gate_role(&self) -> &GateRole

The complete sync role included in the signed routing contract.

pub fn is_remote_root(&self) -> bool

Whether this is a remote root: rows sync unconditionally, and blob locality for the row and descendants is always Remote.

pub fn is_gated_by_descendants(&self) -> bool

Whether this is a gated-by-descendants ancestor (kept alive by its gated subtree rather than by a column of its own).

pub fn blob(&self) -> Option<&BlobDecl>

This table’s blob declaration, if it carries one.

pub fn is_asset(&self) -> bool

Whether this table is an asset of its FK subject (rides the subject’s gate but never grants keep). See SyncedTable::asset.

Trait Implementations

impl Clone for SyncedTable

fn clone(&self) -> SyncedTable

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SyncedTable

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for SyncedTable

fn eq(&self, other: &SyncedTable) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for SyncedTable

impl StructuralPartialEq for SyncedTable