Crate omgbase_sync 

omgbase-sync

The omgbase sync layer, Rust implementation of spec/sync: how bytes get between an omgbase repository (an omgbase_store::Store) and the places they live — the workspace on disk that holds the database, the source registry that says where a repo’s bytes come from, the settings layers, the checkpoint rows and the filesystem fast path (freshness sweep, disk drift, recovery) over a fs::FileSystem seam, the adapter stdio protocol client (external), the driver and the coordinator over an engine::EngineClient, and the advisory locks. pipe is an in-memory pipe with a scripted adapter, for driving the protocol client without a process. The reconciliation itself is the store’s (spec/store §5).

use omgbase_reconcile::Config;
use omgbase_store::Store;
use omgbase_sync::{fs::RealFileSystem, registry, freshness};

let mut store = Store::open(".omgbase/omgbase.db")?;
let repo = registry::ensure_repo(&mut store, "notes", Some("/home/me/notes"))?;
let sweep = freshness::freshness_sweep(
    &mut store, &repo, &RealFileSystem, "/home/me/notes".as_ref(),
    "2026-09-26T10:00:00.000Z", None, &Config::default(),
)?;
println!("{} files scanned, changed: {}", sweep.scanned, sweep.changed);

Re-exports

pub use admin::DiskStatus;

pub use admin::RepoStatus;

pub use admin::SyncStatus;

pub use admin::repos_status;

pub use admin::sync_status;

pub use checkpoint::CheckpointResult;

pub use checkpoint::finish_checkpoint;

pub use checkpoint::process_checkpoint;

pub use coordinator::Coordinator;

pub use coordinator::SyncInSummary;

pub use coordinator::SyncOutSummary;

pub use driver::AttachResult;

pub use driver::attach_source;

pub use driver::reconcile_changes;

pub use engine::DocBytes;

pub use engine::EngineClient;

pub use engine::InProcessEngineClient;

pub use error::Error;

pub use error::Result;

pub use external::ExternalSource;

pub use freshness::DiskDrift;

pub use freshness::SweepPlan;

pub use freshness::SweepResult;

pub use freshness::detect_disk_drift;

pub use freshness::freshness_sweep;

pub use freshness::rebuild_file_stats;

pub use freshness::record_file_stat;

pub use freshness::sweep_plan;

pub use fs::FileStat;

pub use fs::FileSystem;

pub use fs::MemFileSystem;

pub use fs::RealFileSystem;

pub use fs::is_ignored_dir;

pub use lock::WatchLease;

pub use lock::WriterLock;

pub use lock::WriterLockOptions;

pub use lock::pid_alive;

pub use lock::with_writer_lock;

pub use recovery::RecoveryResult;

pub use recovery::recover_repo;

pub use registry::AdapterRow;

pub use registry::SourceRow;

pub use registry::attach;

pub use registry::create_source;

pub use registry::delete_source;

pub use registry::detach;

pub use registry::ensure_adapter;

pub use registry::ensure_repo;

pub use registry::list_adapters;

pub use registry::list_sources;

pub use registry::render_config_flags;

pub use registry::source_by_name;

pub use registry::sources_for_repo;

pub use settings::Settings;

pub use settings::deep_merge;

pub use settings::repo_own_settings;

pub use settings::resolve_settings;

pub use settings::workspace_settings;

pub use settings::write_repo_settings;

pub use settings::write_workspace_settings;

pub use source::SourceCapabilities;

pub use source::SourceEntry;

pub use source::SourceIdentity;

pub use source::SourceItem;

pub use source::SyncSource;

pub use workspace::RepoRow;

pub use workspace::RepoSelection;

pub use workspace::Workspace;

pub use workspace::select_repo;

Modules

admin

Status (spec/sync/README.md §4.4): repos_status and sync_status. Disk agreement is only ever reported from a read-only scan the caller asked for; without one checked is false and nothing is ever green.

checkpoint

Checkpoints (spec/sync/README.md §4.1): one checkpoints row per batch observed through the filesystem fast path or the adapter driver, then the pool sweep.

coordinator

The coordinator (spec/sync/README.md §6): drives a source against an engine client with no reconciliation logic of its own — whole-file bytes in, the change feed out. Loop safety: the engine’s echo gate makes a written file that comes back an echo, and observed commits are never exported.

driver

The driver (spec/sync/README.md §6): the engine-side loop over a SyncSource — reconcile_changes (fetch, observe_batch, checkpoint) and attach_source (ensure_repo, then ingest every enumerated member).

engine

The engine client (spec/sync/README.md §6): the coordinator’s view of “the omgbase side” — observe_many, observe_delete, changes_since, read_doc — behind one trait so the same coordinator runs against an in-process store or a remote server. The in-process client is here; a remote client belongs to the binary that speaks MCP.

error

The crate’s error type.

external

The adapter protocol client (spec/sync/README.md §5): spawn an adapter command with args + render_config_flags(config) and the source’s env, then speak newline-delimited JSON over its stdio — a handshake line, then id-matched requests and responses with ids from 1, plus the unsolicited {"event":"batch"} stream while a watch is live. stdout is the protocol; stderr is inherited for logs.

freshness

The freshness sweep (spec/sync/README.md §4.3): the file_stats cache against a filesystem snapshot — as a pure plan (sweep_plan) and as the I/O around it; read-only disk drift; the cache rebuild.

fs

The filesystem seam (spec/sync/README.md §4.2): the walk over .md files — each directory’s entries in bytewise order of their names, depth-first (§9: Node’s readdir sorts through libuv, so a port whose listing is unsorted sorts) — (mtime_ns, size) stats and reads, behind a trait so the sweep’s I/O stays out of the fixtures. A real implementation over std::fs and an in-memory one over a flat path map that walks the same way.

lock

Locks (spec/sync/README.md §7): advisory O_EXCL lock files under .omgbase/ holding {"pid": <holder>, "ts": <ms>}; a lock whose holder is dead (or whose body is unparsable — §9) is stolen. The writer lock polls; the watch lease is try-only.

pipe

An in-memory pipe: a Write half that hands byte chunks to a blocking Read half over a channel. Lets a test or a conformance runner connect an crate::ExternalSource to a scripted adapter running on a thread without spawning a process. Dropping the writer is EOF for the reader.

recovery

Startup recovery (spec/sync/README.md §4.3 “Recovery”): every live doc’s file is checked against its current revision; a divergent file is re-ingested as an observed commit, one document at a time (§9).

registry

The source registry (spec/sync/README.md §2): adapters, sources, attachments (sync_state is reserved — only delete_source touches it), ensure_repo with the <slug>-fs source, and the config → argv rendering an adapter is spawned with.

settings

Settings (spec/sync/README.md §3): one schema at two layers — the workspace_settings singleton (defaults) and repos.settings (overrides) — resolved by a deep merge.

source

The sync source contract (spec/sync/README.md §5): the in-engine view of an adapter — capabilities, enumerate/fetch, write/remove when it writes through, a watch stream when it can watch. Every call crosses a pipe in production (crate::external::ExternalSource); an in-memory source serves tests.

workspace

The workspace (spec/sync/README.md §1): the directory holding .omgbase/, discovered by walking up like git; its repos with their derived root paths; repo selection for a command run in some cwd.

Structs

ChangesPage

A page of the feed.

CommitDigest

One commit of the feed.

DeleteOutcome

The outcome of observing that a path is gone (§5.6).

DigestRevision

One revision a commit wrote.

ObserveOutcome

The outcome of observing bytes at a path (§5.4).

Constants

PROTOCOL_VERSION

The adapter protocol number the handshake must carry (spec/sync §5).

SPEC_VERSION

The spec/sync/VERSION this crate implements (major.minor).

Functions

now_ts

The current time as the store writes it (spec/store §2.4: YYYY-MM-DDTHH:MM:SS.fffZ).