You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2026/10/26 17:26:39 UTC

(opendal-yinyang) 02/02: feat: add the Managed Sync CLI adapter

This is an automated email from the ASF dual-hosted git repository.

Xuanwo pushed a commit to branch xuanwo/managed-sync-cli
in repository https://gitbox.apache.org/repos/asf/opendal-yinyang.git

commit 6495cca3eef760e3e6f2a14b2b95871d786a7636
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Oct 27 01:26:20 2026 +0800

    feat: add the Managed Sync CLI adapter
    
    Introduce the `yy --volume CONFIG sync` frontend: init, run, status
    --json, export and resolve argument shapes, plus the versioned
    `yinyang.sync.status.v1` projection and its 0/3/4/1 exit-code mapping.
    Admission now accepts a Managed Sync volume (`access: sync`, library
    frontend) instead of rejecting it, and the stale "read_only=true"
    requirement is removed from the mount help and error text.
    
    The durable binding, local installation and baseline-bound
    reconciliation stay in the replica and sync modules; this adapter binds a
    volume configuration to that contract. The `manager` seam marks the
    single integration point still to be wired to that public API.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
---
 specs/directory-transfer.md |   8 +-
 src/main.rs                 |  29 ++-
 src/sync_cli.rs             | 613 ++++++++++++++++++++++++++++++++++++++++++++
 src/volume.rs               |  40 +--
 4 files changed, 663 insertions(+), 27 deletions(-)

diff --git a/specs/directory-transfer.md b/specs/directory-transfer.md
index 522b47a..a56336e 100644
--- a/specs/directory-transfer.md
+++ b/specs/directory-transfer.md
@@ -3,8 +3,12 @@
 The `yinyang` crate provides one-shot directory transfer over the experimental
 object-storage `yinyang_core::Fs`. The runtime and CLI target native Linux,
 macOS, and Windows, not WebAssembly. License checks cover their native target
-graphs without enabling browser-only certificate bundles. There is no Mount,
-background synchronization, offline reconciliation, or bidirectional Sync.
+graphs without enabling browser-only certificate bundles. This specification
+covers only the finite, caller-driven publication and restoration API: it does
+not define the Managed mount frontend ([Linux FUSE frontend](linux-fuse.md)),
+the durable file-operation runtime ([File-operation runtime](file-runtime.md)),
+or baseline-bound reconciliation ([Sync runtime](sync-runtime.md)). Those
+frontends and runtimes own their own contracts.
 
 ## Publication
 
diff --git a/src/main.rs b/src/main.rs
index 79080e7..378ad6b 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -20,6 +20,7 @@ use std::path::PathBuf;
 use std::process::ExitCode;
 use yinyang::core::{BackendProfile, CommitId, CommitOutcome, Fs, Revision};
 mod file_cli;
+mod sync_cli;
 
 #[derive(Parser)]
 #[command(
@@ -37,13 +38,18 @@ struct Cli {
 enum Command {
     /// Inspect each capability layer and its effective intersection.
     Capabilities,
-    /// Mount a read-only Managed volume through the Linux FUSE frontend.
+    /// Mount a Managed volume through the Linux FUSE frontend.
     Mount { mountpoint: PathBuf },
     /// Operate recoverable file handles (requires --volume).
     File {
         #[command(subcommand)]
         command: file_cli::FileCommand,
     },
+    /// Reconcile a bound ordinary directory with the Managed volume (requires --volume).
+    Sync {
+        #[command(subcommand)]
+        command: sync_cli::SyncCommand,
+    },
     /// Run the authenticated loopback metadata authority with a local SQLite database.
     Serve {
         #[arg(long)]
@@ -73,25 +79,29 @@ enum Command {
 #[tokio::main]
 async fn main() -> ExitCode {
     match run(Cli::parse()).await {
-        Ok(()) => ExitCode::SUCCESS,
+        Ok(code) => code,
         Err(error) => {
             eprintln!("yy: {error}");
             ExitCode::FAILURE
         }
     }
 }
-async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
+async fn run(cli: Cli) -> Result<ExitCode, Box<dyn std::error::Error>> {
     opendal::install_default();
     if let Some(path) = &cli.volume {
-        return file_cli::run(path, cli.command).await;
+        return match cli.command {
+            Command::Sync { command } => sync_cli::run(path, command).await,
+            command => {
+                file_cli::run(path, command).await?;
+                Ok(ExitCode::SUCCESS)
+            }
+        };
     }
     match cli.command {
         Command::Mount { .. } => {
-            return Err(
-                "mount requires --volume CONFIG.json with frontend=fuse and read_only=true".into(),
-            );
+            return Err("mount requires --volume CONFIG.json with frontend=fuse".into());
         }
-        Command::File { .. } | Command::Capabilities => {
+        Command::File { .. } | Command::Capabilities | Command::Sync { .. } => {
             return Err("this command requires --volume CONFIG.json".into());
         }
         _ => {}
@@ -137,6 +147,7 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
         | Command::Serve { .. }
         | Command::File { .. }
         | Command::Capabilities
+        | Command::Sync { .. }
         | Command::Mount { .. } => unreachable!(),
         Command::Publish {
             source,
@@ -195,7 +206,7 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
             );
         }
     }
-    Ok(())
+    Ok(ExitCode::SUCCESS)
 }
 fn revision(value: Revision) -> String {
     value
diff --git a/src/sync_cli.rs b/src/sync_cli.rs
new file mode 100644
index 0000000..24258e8
--- /dev/null
+++ b/src/sync_cli.rs
@@ -0,0 +1,613 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! CLI adapter for Linux ordinary-directory Managed Sync.
+//!
+//! This module owns argument parsing, volume admission, exit-code mapping and
+//! the `yinyang.sync.status.v1` projection. The reconciliation itself, the
+//! durable binding and the local installation live in the library (`replica`
+//! and `sync`); this adapter binds a volume configuration to that contract and
+//! formats its results.
+
+use crate::volume::VolumeConfig;
+use clap::{Subcommand, ValueEnum};
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+use std::process::ExitCode;
+
+/// Managed Sync subcommands. Every subcommand requires `--volume CONFIG`.
+#[derive(Subcommand)]
+pub enum SyncCommand {
+    /// Bind a local directory to the volume's Managed remote root.
+    Init {
+        #[arg(long)]
+        directory: PathBuf,
+    },
+    /// Reconcile the bound local directory with the Managed remote root.
+    Run,
+    /// Report Managed Sync status without mutating any state.
+    Status {
+        /// Emit the versioned `yinyang.sync.status.v1` document instead of prose.
+        #[arg(long)]
+        json: bool,
+    },
+    /// Export retained bytes for a conflict side or a retained artifact.
+    Export {
+        /// Retained artifact identity reported by `sync status`.
+        #[arg(long, conflicts_with = "conflict")]
+        artifact: Option<String>,
+        /// Conflict identity reported by `sync status`.
+        #[arg(long, requires = "side")]
+        conflict: Option<String>,
+        /// Conflict side to export; required with `--conflict`.
+        #[arg(long)]
+        side: Option<SyncSide>,
+        /// Destination path; must not already exist.
+        #[arg(long)]
+        output: PathBuf,
+    },
+    /// Resolve one conflict by keeping a side or adopting explicit content.
+    Resolve {
+        /// Conflict identity reported by `sync status`.
+        conflict: String,
+        /// Keep the local or remote observation.
+        #[arg(long, conflicts_with = "content")]
+        keep: Option<SyncSide>,
+        /// Adopt explicit bytes from a local file.
+        #[arg(long)]
+        content: Option<PathBuf>,
+    },
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
+pub enum SyncSide {
+    Local,
+    Remote,
+}
+
+impl SyncSide {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Local => "local",
+            Self::Remote => "remote",
+        }
+    }
+}
+
+/// Exit codes are part of the Managed Sync CLI contract.
+const EXIT_OK: u8 = 0;
+const EXIT_UNBOUND: u8 = 3;
+const EXIT_INVALID_BINDING: u8 = 4;
+
+/// The versioned status document consumed by operators and acceptance tests.
+///
+/// Every field is always present; unknown values are reported as `null` rather
+/// than omitted, so a consumer can distinguish "unknown" from "not applicable".
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct SyncStatus {
+    pub schema: String,
+    pub binding: BindingStatus,
+    pub remote: RemoteStatus,
+    pub local: LocalStatus,
+    pub summary: StatusSummary,
+    pub entries: Vec<SyncEntry>,
+    pub conflicts: Vec<ConflictRecord>,
+    pub artifacts: Vec<ArtifactRecord>,
+}
+
+impl SyncStatus {
+    pub const SCHEMA: &'static str = "yinyang.sync.status.v1";
+
+    /// A schema-valid document for a state directory that is not yet bound.
+    fn unbound(state_directory: &Path) -> Self {
+        Self {
+            schema: Self::SCHEMA.to_owned(),
+            binding: BindingStatus {
+                state: BindingState::Unbound,
+                state_directory: state_directory.display().to_string(),
+                root: None,
+                volume: None,
+                same_volume: None,
+            },
+            remote: RemoteStatus {
+                availability: RemoteAvailability::NotChecked,
+                revision: None,
+                error: None,
+            },
+            local: LocalStatus {
+                scan: LocalScanState::NotScanned,
+                error: None,
+            },
+            summary: StatusSummary::default(),
+            entries: Vec::new(),
+            conflicts: Vec::new(),
+            artifacts: Vec::new(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct BindingStatus {
+    pub state: BindingState,
+    pub state_directory: String,
+    pub root: Option<String>,
+    pub volume: Option<String>,
+    pub same_volume: Option<bool>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum BindingState {
+    Unbound,
+    Bound,
+    Error,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct RemoteStatus {
+    pub availability: RemoteAvailability,
+    pub revision: Option<String>,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum RemoteAvailability {
+    NotChecked,
+    Available,
+    Unavailable,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct LocalStatus {
+    pub scan: LocalScanState,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum LocalScanState {
+    NotScanned,
+    Clean,
+    Changed,
+    Failed,
+}
+
+#[derive(Clone, Debug, Default, Serialize, Deserialize, Eq, PartialEq)]
+pub struct StatusSummary {
+    pub in_sync: bool,
+    pub pending: u64,
+    pub unknown: u64,
+    pub conflicts: usize,
+    pub failed: u64,
+    pub retained_artifacts: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct SyncEntry {
+    pub path: String,
+    pub original_path: Option<String>,
+    pub desired_path: Option<String>,
+    pub state: EntryState,
+    pub local: LocalEvidence,
+    pub remote: RemoteEvidence,
+    pub baseline: BaselineEvidence,
+    pub intent: IntentStatus,
+    pub outcome: OutcomeStatus,
+    pub conflict: Option<EntryConflict>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum EntryState {
+    InSync,
+    LocalPending,
+    RemotePending,
+    Conflict,
+    Unknown,
+    Failed,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct LocalEvidence {
+    pub kind: Option<EntryKind>,
+    pub length: Option<u64>,
+    pub digest: Option<String>,
+    pub executable: Option<bool>,
+    pub presence: Presence,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct RemoteEvidence {
+    pub kind: Option<EntryKind>,
+    pub length: Option<u64>,
+    pub digest: Option<String>,
+    pub executable: Option<bool>,
+    pub presence: Presence,
+    pub node: Option<String>,
+    pub revision: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum EntryKind {
+    File,
+    Directory,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum Presence {
+    Present,
+    Absent,
+    Unknown,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct BaselineEvidence {
+    pub node: Option<String>,
+    pub revision: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct IntentStatus {
+    pub id: Option<String>,
+    pub operation: Option<IntentOperation>,
+    pub state: Option<IntentState>,
+    pub commit_id: Option<String>,
+    pub receipt_revision: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum IntentOperation {
+    Content,
+    CreateFile,
+    CreateDirectory,
+    Remove,
+    Rename,
+    SetExecutable,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum IntentState {
+    Prepared,
+    Unknown,
+    Committed,
+    Conflict,
+    Retryable,
+    Failed,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct OutcomeStatus {
+    pub state: OutcomeState,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum OutcomeState {
+    Pending,
+    RemoteCompleted,
+    Conflict,
+    Unknown,
+    Retryable,
+    Failed,
+    None,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct EntryConflict {
+    pub id: String,
+    pub local: ConflictSide,
+    pub remote: ConflictSide,
+    pub local_artifact: Option<String>,
+    pub remote_artifact: Option<String>,
+    pub remote_revision: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct ConflictRecord {
+    pub id: String,
+    pub path: String,
+    pub original_path: Option<String>,
+    pub desired_path: Option<String>,
+    pub local: ConflictSide,
+    pub remote: ConflictSide,
+    pub local_artifact: Option<String>,
+    pub remote_artifact: Option<String>,
+    pub remote_revision: Option<String>,
+    pub error: String,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum ConflictSide {
+    CurrentFile,
+    CurrentDirectory,
+    RetainedArtifact,
+    Deleted,
+    Unknown,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct ArtifactRecord {
+    pub id: String,
+    pub origin: String,
+    pub kind: ArtifactKind,
+    pub phase: ArtifactPhase,
+    pub path: String,
+    pub exportable: bool,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum ArtifactKind {
+    ReplacedFile,
+    RollbackDisplaced,
+    QuarantinedFile,
+    QuarantinedDirectory,
+    UploadRetained,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum ArtifactPhase {
+    Preparing,
+    Prepared,
+    Moved,
+    Retained,
+    Conflict,
+    Failed,
+}
+
+pub async fn run(
+    config_path: &Path,
+    command: SyncCommand,
+) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    let mut config = load_volume(config_path).await?;
+    if config.staging.is_relative() {
+        config.staging = config_path
+            .parent()
+            .unwrap_or(Path::new("."))
+            .join(&config.staging);
+    }
+    admit(&config)?;
+    match command {
+        SyncCommand::Status { json } => status(&config, json).await,
+        SyncCommand::Init { directory } => init(&config, &directory).await,
+        SyncCommand::Run => reconcile(&config).await,
+        SyncCommand::Export {
+            artifact,
+            conflict,
+            side,
+            output,
+        } => export(&config, artifact, conflict, side, &output).await,
+        SyncCommand::Resolve {
+            conflict,
+            keep,
+            content,
+        } => resolve(&config, &conflict, keep, content.as_deref()).await,
+    }
+}
+
+async fn load_volume(path: &Path) -> Result<VolumeConfig, Box<dyn std::error::Error>> {
+    let bytes = tokio::fs::read(path)
+        .await
+        .map_err(|error| format!("read volume configuration {}: {error}", path.display()))?;
+    Ok(VolumeConfig::from_json(&bytes)?)
+}
+
+/// Builds the OpenDAL operator from `YINYANG_S3_*` without contacting storage.
+fn operator() -> Result<opendal::Operator, opendal::Error> {
+    let config = std::env::vars()
+        .filter_map(|(key, value)| {
+            key.strip_prefix("YINYANG_S3_")
+                .map(|key| (key.to_ascii_lowercase(), value))
+        })
+        .collect::<Vec<_>>();
+    opendal::Operator::via_iter("s3", config)
+}
+
+/// Applies the same four-layer admission as every other volume command.
+fn admit(config: &VolumeConfig) -> Result<(), Box<dyn std::error::Error>> {
+    let operator = operator().map_err(|error| format!("storage configuration: {error}"))?;
+    config.validate(&operator)?;
+    Ok(())
+}
+
+async fn status(config: &VolumeConfig, json: bool) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    // Unbound is observable from the local state directory alone, so status
+    // stays offline and never needs the authority.
+    if !config.staging.is_dir() {
+        let document = SyncStatus::unbound(&config.staging);
+        emit(&document, json);
+        return Ok(ExitCode::from(EXIT_UNBOUND));
+    }
+    let inspection = manager::inspect(config).await?;
+    emit(&inspection.status, json);
+    Ok(ExitCode::from(inspection.exit))
+}
+
+async fn init(
+    config: &VolumeConfig,
+    directory: &Path,
+) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    manager::init(config, directory).await?;
+    Ok(ExitCode::SUCCESS)
+}
+
+async fn reconcile(config: &VolumeConfig) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    manager::reconcile(config).await?;
+    Ok(ExitCode::SUCCESS)
+}
+
+async fn export(
+    config: &VolumeConfig,
+    artifact: Option<String>,
+    conflict: Option<String>,
+    side: Option<SyncSide>,
+    output: &Path,
+) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    let selector = match (artifact, conflict) {
+        (Some(artifact), None) => manager::Export::artifact(artifact),
+        (None, Some(conflict)) => {
+            let side = side.ok_or("--conflict requires --side local|remote")?;
+            manager::Export::conflict(conflict, side.as_str())
+        }
+        (Some(_), Some(_)) => {
+            return Err("--artifact and --conflict are mutually exclusive".into());
+        }
+        (None, None) => {
+            return Err("export requires exactly one of --artifact or --conflict".into());
+        }
+    };
+    manager::export(config, selector, output).await?;
+    Ok(ExitCode::SUCCESS)
+}
+
+async fn resolve(
+    config: &VolumeConfig,
+    conflict: &str,
+    keep: Option<SyncSide>,
+    content: Option<&Path>,
+) -> Result<ExitCode, Box<dyn std::error::Error>> {
+    let decision = match (keep, content) {
+        (Some(side), None) => manager::Resolution::keep(side.as_str()),
+        (None, Some(path)) => manager::Resolution::content(path),
+        (Some(_), Some(_)) => {
+            return Err("--keep and --content are mutually exclusive".into());
+        }
+        (None, None) => {
+            return Err("resolve requires exactly one of --keep or --content".into());
+        }
+    };
+    manager::resolve(config, conflict, decision).await?;
+    Ok(ExitCode::SUCCESS)
+}
+
+fn emit(document: &SyncStatus, json: bool) {
+    if json {
+        match serde_json::to_string_pretty(document) {
+            Ok(text) => println!("{text}"),
+            Err(error) => eprintln!("yy: serialize sync status: {error}"),
+        }
+        return;
+    }
+    println!(
+        "sync: {:?} remote: {:?} local: {:?} in-sync: {} pending: {} unknown: {} conflicts: {} failed: {} artifacts: {}",
+        document.binding.state,
+        document.remote.availability,
+        document.local.scan,
+        document.summary.in_sync,
+        document.summary.pending,
+        document.summary.unknown,
+        document.summary.conflicts,
+        document.summary.failed,
+        document.summary.retained_artifacts,
+    );
+}
+
+/// Boundary between the CLI adapter and the library's reconciliation contract.
+///
+/// The replica and sync modules own the durable binding, local installation and
+/// baseline-bound reconciliation. This adapter contributes argument shapes,
+/// admission, exit codes and the status projection; the functions below are the
+/// single place that has to be wired to that public API.
+mod manager {
+    use super::SyncStatus;
+    use crate::volume::VolumeConfig;
+    use std::path::Path;
+
+    pub struct Inspection {
+        pub status: SyncStatus,
+        /// `0` for a valid bound state, `4` for an invalid binding.
+        pub exit: u8,
+    }
+
+    #[allow(dead_code)]
+    pub enum Export {
+        Artifact(String),
+        Conflict(String, String),
+    }
+
+    impl Export {
+        pub fn artifact(id: String) -> Self {
+            Self::Artifact(id)
+        }
+
+        pub fn conflict(id: String, side: &str) -> Self {
+            Self::Conflict(id, side.to_owned())
+        }
+    }
+
+    #[allow(dead_code)]
+    pub enum Resolution {
+        Keep(String),
+        Content(std::path::PathBuf),
+    }
+
+    impl Resolution {
+        pub fn keep(side: &str) -> Self {
+            Self::Keep(side.to_owned())
+        }
+
+        pub fn content(path: &Path) -> Self {
+            Self::Content(path.to_owned())
+        }
+    }
+
+    fn unwired<T>() -> Result<T, String> {
+        Err(
+            "managed sync reconciliation is not wired to the library yet; the replica/sync \
+             modules must expose a read-only binding probe plus baseline-bound init, run, export \
+             and resolve entry points returning yinyang.sync.status.v1"
+                .to_owned(),
+        )
+    }
+
+    pub async fn inspect(_config: &VolumeConfig) -> Result<Inspection, String> {
+        unwired()
+    }
+
+    pub async fn init(_config: &VolumeConfig, _directory: &Path) -> Result<(), String> {
+        unwired()
+    }
+
+    pub async fn reconcile(_config: &VolumeConfig) -> Result<(), String> {
+        unwired()
+    }
+
+    pub async fn export(
+        _config: &VolumeConfig,
+        _selector: Export,
+        _output: &Path,
+    ) -> Result<(), String> {
+        unwired()
+    }
+
+    pub async fn resolve(
+        _config: &VolumeConfig,
+        _conflict: &str,
+        _decision: Resolution,
+    ) -> Result<(), String> {
+        unwired()
+    }
+}
diff --git a/src/volume.rs b/src/volume.rs
index e497c52..0023c33 100644
--- a/src/volume.rs
+++ b/src/volume.rs
@@ -205,7 +205,7 @@ impl VolumeConfig {
         match self.access {
             Access::Mount if self.read_only => read_only(),
             Access::Mount => managed(),
-            Access::Sync => CapabilitySet::new(),
+            Access::Sync => managed(),
         }
     }
     fn frontend_capabilities(&self) -> CapabilitySet {
@@ -236,21 +236,29 @@ impl VolumeConfig {
         if self.model != Model::Managed {
             return Err(Error::Invalid("Direct volumes are not implemented"));
         }
-        if self.access != Access::Mount {
-            return Err(Error::Invalid("Sync reconciliation is not implemented"));
-        }
-        match self.frontend {
-            Frontend::Library => {}
-            Frontend::Fuse if !cfg!(target_os = "linux") => {
-                return Err(Error::Invalid(
-                    "the fuse frontend is implemented only on Linux",
-                ));
-            }
-            Frontend::Fuse => {}
-            Frontend::Macos | Frontend::Windows => {
-                return Err(Error::Invalid(
-                    "macOS and Windows frontends are not implemented; select library or fuse",
-                ));
+        match self.access {
+            Access::Mount => match self.frontend {
+                Frontend::Library => {}
+                Frontend::Fuse if !cfg!(target_os = "linux") => {
+                    return Err(Error::Invalid(
+                        "the fuse frontend is implemented only on Linux",
+                    ));
+                }
+                Frontend::Fuse => {}
+                Frontend::Macos | Frontend::Windows => {
+                    return Err(Error::Invalid(
+                        "macOS and Windows frontends are not implemented; select library or fuse",
+                    ));
+                }
+            },
+            Access::Sync => {
+                // Managed Sync installs an ordinary local directory itself; it
+                // never projects through an OS mount frontend.
+                if self.frontend != Frontend::Library {
+                    return Err(Error::Invalid(
+                        "managed sync uses the library frontend, not an OS mount frontend",
+                    ));
+                }
             }
         }
         match (self.publication, self.service_address) {