kopiur_kopia/

model.rs

//! Typed models for kopia `--json` output (kopia 0.23).
//!
//! These structs are modeled against the *actual* JSON kopia emits, captured by
//! round-tripping a filesystem repository. Field names match kopia's keys
//! exactly via `#[serde(rename_all = "camelCase")]` (plus explicit `rename`s
//! where kopia diverges, e.g. `uniqueIDHex`). None of these use
//! `deny_unknown_fields`: kopia adds fields across releases and we must tolerate
//! them. Times are `chrono::DateTime<Utc>`.
//!
//! Note on stdout vs stderr: kopia prints its progress (`Snapshotting ...`,
//! `Restored N files`) to **stderr** and the machine-readable `--json` result
//! to **stdout**. The client parses stdout only.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// Strip kopia's `tag:` manifest-key prefix from a snapshot `tags` map, yielding the
/// tags under the keys the CLI was given (`--tags key:value` → manifest `tag:key`).
///
/// kopia splits each `--tags` argument on the FIRST colon and stores the key with a
/// `tag:` prefix in the manifest (verified against the pinned 0.23.1 binary by
/// `integration_roundtrip::tag_mechanics_...`). Keys without the prefix are kept
/// verbatim, so a kopia release that dropped the prefix would degrade gracefully
/// instead of hiding every tag.
///
/// ```
/// use std::collections::BTreeMap;
/// let mut m = BTreeMap::new();
/// m.insert("tag:kopiur-meta".to_string(), "{\"schema\":1}".to_string());
/// m.insert("bare".to_string(), "kept".to_string());
/// let u = kopiur_kopia::user_tags(&m);
/// assert_eq!(u.get("kopiur-meta").map(String::as_str), Some("{\"schema\":1}"));
/// assert_eq!(u.get("bare").map(String::as_str), Some("kept"));
/// ```
pub fn user_tags(tags: &BTreeMap<String, String>) -> BTreeMap<String, String> {
    tags.iter()
        .map(|(k, v)| (k.strip_prefix("tag:").unwrap_or(k).to_string(), v.clone()))
        .collect()
}

/// Kopia's snapshot identity triple: `userName@host:path`. Present on both
/// snapshot-create results and snapshot-list entries.
///
/// kopia's JSON spells the user component `userName`; the typed field is
/// `user_name`:
///
/// ```
/// use kopiur_kopia::SnapshotSource;
///
/// let src: SnapshotSource =
///     serde_json::from_str(r#"{"host":"prod","userName":"mydb","path":"/data"}"#).unwrap();
/// assert_eq!(src.user_name, "mydb");
/// assert_eq!(src.identity(), "mydb@prod:/data");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotSource {
    /// The kopia "host" component of identity.
    pub host: String,
    /// The kopia "user" component of identity. kopia's JSON key is `userName`.
    pub user_name: String,
    /// The absolute source path that was snapshotted.
    pub path: String,
}

impl SnapshotSource {
    /// Render kopia's canonical `user@host:path` identity string.
    pub fn identity(&self) -> String {
        format!("{}@{}:{}", self.user_name, self.host, self.path)
    }
}

/// Directory summary embedded under a root entry (`summ`). Carries the
/// aggregate counts kopia computed while walking the tree.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirSummary {
    /// Total logical size in bytes.
    #[serde(default)]
    pub size: u64,
    /// Number of files.
    #[serde(default)]
    pub files: u64,
    /// Number of symlinks.
    #[serde(default)]
    pub symlinks: u64,
    /// Number of directories.
    #[serde(default)]
    pub dirs: u64,
    /// Newest mtime found in the tree.
    #[serde(default, rename = "maxTime")]
    pub max_time: Option<DateTime<Utc>>,
    /// Count of entries that failed during the walk **as fatal errors**. NOTE: this is
    /// `0` when the failures were *ignored* by an `ignore-file-errors`/`ignore-dir-errors`
    /// policy — in that case the snapshot still completes (exit 0) but the entries are in
    /// [`DirSummary::errors`], which is the reliable "what got skipped" signal.
    #[serde(default, rename = "numFailed")]
    pub num_failed: u64,
    /// Per-entry errors kopia hit while walking the tree (e.g. `permission denied`).
    /// Populated whether the errors were fatal (exit 1) OR ignored by policy (exit 0), so
    /// this is how an otherwise-silent *incomplete* snapshot is detected.
    #[serde(default)]
    pub errors: Vec<EntryError>,
    /// kopia's `IncompleteReason` mirrored into the root summary (`checkpoint`,
    /// `canceled`, …). See [`SnapshotListEntry::incomplete_reason`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub incomplete: Option<String>,
}

/// One `{path, error}` entry from a snapshot's `rootEntry.summ.errors`. Kopia records the
/// source-relative path and the full error string for every entry it could not include.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EntryError {
    /// Source-relative path of the entry that failed (e.g. `secret_dir`).
    #[serde(default)]
    pub path: String,
    /// The full error string (e.g. `... permission denied`).
    #[serde(default)]
    pub error: String,
}

/// The `rootEntry` of a snapshot — the top directory object plus its summary.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RootEntry {
    /// Entry name (basename of the snapshotted path).
    #[serde(default)]
    pub name: String,
    /// Entry type, e.g. "d" for directory.
    #[serde(default, rename = "type")]
    pub entry_type: String,
    /// The kopia object id of the root (the `k...` handle).
    #[serde(default)]
    pub obj: String,
    /// Aggregate directory summary. Optional because non-directory roots omit
    /// it.
    #[serde(default, rename = "summ")]
    pub summary: Option<DirSummary>,
}

/// Result of `kopia snapshot create <path> --json`.
///
/// kopia emits a single JSON object on stdout. The aggregate counts live under
/// `rootEntry.summ`; the create result itself does not carry a top-level
/// `stats` block (that appears on snapshot-list entries). We surface
/// convenience accessors for the common stats the mover reports.
///
/// Parse a representative kopia create result and read the convenience
/// accessors that pull from `rootEntry.summ`:
///
/// ```
/// use kopiur_kopia::SnapshotCreateResult;
///
/// let json = r#"{
///     "id": "k9c0ffee",
///     "source": {"host": "prod", "userName": "mydb", "path": "/data"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z",
///     "rootEntry": {
///         "name": "data", "type": "d", "obj": "k1",
///         "summ": {"size": 4096, "files": 12, "dirs": 3, "numFailed": 1}
///     }
/// }"#;
/// let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
/// assert_eq!(r.id, "k9c0ffee");
/// assert_eq!(r.source.identity(), "mydb@prod:/data");
/// assert_eq!(r.total_bytes(), 4096);
/// assert_eq!(r.file_count(), 12);
/// assert_eq!(r.error_count(), 1);
/// ```
///
/// The accessors return `0` when the root summary is absent rather than
/// panicking:
///
/// ```
/// use kopiur_kopia::SnapshotCreateResult;
///
/// let json = r#"{
///     "id": "k1",
///     "source": {"host": "h", "userName": "u", "path": "/p"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z"
/// }"#;
/// let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
/// assert_eq!(r.total_bytes(), 0);
/// assert_eq!(r.file_count(), 0);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotCreateResult {
    /// The new snapshot's manifest id.
    pub id: String,
    /// Identity of the snapshot.
    pub source: SnapshotSource,
    /// Free-form description (usually empty).
    #[serde(default)]
    pub description: String,
    /// When the snapshot started.
    pub start_time: DateTime<Utc>,
    /// When the snapshot finished.
    pub end_time: DateTime<Utc>,
    /// Root directory entry with its summary.
    #[serde(default)]
    pub root_entry: Option<RootEntry>,
    /// Snapshot tags as stored on the manifest — keys carry kopia's `tag:` prefix
    /// (strip with [`user_tags`]). Empty for untagged snapshots and on kopia
    /// versions that omit the field; an empty map is elided on re-serialization
    /// (these types also ride the mover result wire).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub tags: BTreeMap<String, String>,
}

/// What a `kopia snapshot create` actually did.
///
/// Two outcomes, both successes, and they are NOT interchangeable:
///
/// * [`Created`](Self::Created) — a new manifest exists and this run owns it.
/// * [`Unchanged`](Self::Unchanged) — kopia declined to write one because the
///   source is byte-identical to the previous snapshot (its retention knob
///   `ignoreIdenticalSnapshots`). There is **no new manifest**, and crucially
///   nothing this run may claim: the newest manifest for this identity belongs
///   to the *previous* `Snapshot` CR, which owns it via a finalizer and will
///   delete it when retention prunes that CR.
///
/// Modelled as an enum rather than `Option<SnapshotCreateResult>` so the
/// distinction cannot be `unwrap_or_default`-ed away. Collapsing it is exactly
/// the bug: a deduped run recorded as an ordinary success goes looking for
/// "its" snapshot, finds its predecessor's, and two CRs end up claiming one
/// manifest (#351).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnapshotCreateOutcome {
    /// kopia wrote a new manifest; this run owns it.
    ///
    /// Boxed so the enum stays small: `SnapshotCreateResult` is ~320 bytes and
    /// `Unchanged` is zero-sized, and every caller moves the result out
    /// immediately.
    Created(Box<SnapshotCreateResult>),
    /// kopia deduped: nothing changed, so no manifest was written and this run
    /// owns nothing. The previous snapshot remains the live restore point.
    Unchanged,
}

impl SnapshotCreateResult {
    /// Total logical bytes in the snapshot, from the root summary (0 if absent).
    pub fn total_bytes(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.size)
            .unwrap_or(0)
    }

    /// Total file count in the snapshot, from the root summary (0 if absent).
    pub fn file_count(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.files)
            .unwrap_or(0)
    }

    /// Number of entries that failed during the walk (0 if absent).
    pub fn error_count(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.num_failed)
            .unwrap_or(0)
    }

    /// The per-entry errors kopia recorded (empty if none / absent). Non-empty even when
    /// the errors were *ignored* by policy (exit 0) — the canonical signal that a snapshot
    /// is **incomplete** (some source entries were skipped).
    pub fn entry_errors(&self) -> &[EntryError] {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.errors.as_slice())
            .unwrap_or(&[])
    }
}

/// The `stats` block present on each `kopia snapshot list --json` entry. These
/// are the new/modified/unchanged-style counters.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotStats {
    /// Total logical size of all included files.
    #[serde(default)]
    pub total_size: u64,
    /// Size excluded by policy.
    #[serde(default)]
    pub excluded_total_size: u64,
    /// Number of files included.
    #[serde(default)]
    pub file_count: u64,
    /// Files served from cache (unchanged since the prior snapshot).
    #[serde(default)]
    pub cached_files: u64,
    /// Files re-read because they were new or modified.
    #[serde(default)]
    pub non_cached_files: u64,
    /// Number of directories.
    #[serde(default)]
    pub dir_count: u64,
    /// Files excluded by policy.
    #[serde(default)]
    pub excluded_file_count: u64,
    /// Directories excluded by policy.
    #[serde(default)]
    pub excluded_dir_count: u64,
    /// Errors that were ignored (per ignore-error policy).
    #[serde(default)]
    pub ignored_error_count: u64,
    /// Hard errors encountered.
    #[serde(default)]
    pub error_count: u64,
}

/// One entry from `kopia snapshot list --json`.
///
/// Unlike the create result, list entries carry a top-level `stats` block and a
/// `retentionReason` array (the kopia GFS classes keeping the snapshot alive):
///
/// ```
/// use kopiur_kopia::SnapshotListEntry;
///
/// let json = r#"{
///     "id": "k1",
///     "source": {"host": "prod", "userName": "mydb", "path": "/data"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z",
///     "stats": {"totalSize": 4096, "fileCount": 12, "errorCount": 0},
///     "retentionReason": ["latest-1", "daily-1"]
/// }"#;
/// let entry: SnapshotListEntry = serde_json::from_str(json).unwrap();
/// assert_eq!(entry.id, "k1");
/// assert_eq!(entry.stats.total_size, 4096);
/// assert_eq!(entry.stats.file_count, 12);
/// assert_eq!(entry.retention_reason, vec!["latest-1", "daily-1"]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotListEntry {
    /// The snapshot manifest id.
    pub id: String,
    /// Identity of the snapshot.
    pub source: SnapshotSource,
    /// Free-form description.
    #[serde(default)]
    pub description: String,
    /// When the snapshot started.
    pub start_time: DateTime<Utc>,
    /// When the snapshot finished.
    pub end_time: DateTime<Utc>,
    /// Per-snapshot statistics.
    #[serde(default)]
    pub stats: SnapshotStats,
    /// Root directory entry.
    #[serde(default)]
    pub root_entry: Option<RootEntry>,
    /// Why this snapshot is being retained (kopia GFS reasons such as
    /// `latest-1`, `daily-1`). Empty for snapshots outside any retention class.
    #[serde(default)]
    pub retention_reason: Vec<String>,
    /// Snapshot tags as stored on the manifest — keys carry kopia's `tag:` prefix
    /// (strip with [`user_tags`]). Empty for untagged snapshots and on kopia
    /// versions that omit the field; an empty map is elided on re-serialization
    /// (these types also ride the mover result wire).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub tags: BTreeMap<String, String>,
    /// kopia's `IncompleteReason`: set (`checkpoint`, `canceled`, …) on a
    /// manifest an interrupted `snapshot create` left behind. kopia's JSON
    /// listing emits these even WITHOUT `--incomplete` (that flag only filters
    /// the text output) — read it through [`Self::incomplete_reason`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub incomplete: Option<String>,
}

impl SnapshotListEntry {
    /// Why this manifest is NOT a complete snapshot, or `None` for a complete
    /// one. Reads the top-level marker, falling back to `rootEntry.summ`
    /// (kopia writes both); an empty string is kopia's `omitempty` "complete".
    /// Deliberately an open string, not an enum: ANY reason means incomplete,
    /// so a reason kopia adds later can never be mistaken for complete.
    pub fn incomplete_reason(&self) -> Option<&str> {
        let summ = self
            .root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .and_then(|s| s.incomplete.as_deref());
        [self.incomplete.as_deref(), summ]
            .into_iter()
            .flatten()
            .find(|r| !r.is_empty())
    }
}

/// Split a raw `snapshot list --json` result into `(complete, incomplete)`,
/// preserving order. See [`SnapshotListEntry::incomplete_reason`].
pub fn partition_incomplete(
    entries: Vec<SnapshotListEntry>,
) -> (Vec<SnapshotListEntry>, Vec<SnapshotListEntry>) {
    entries
        .into_iter()
        .partition(|e| e.incomplete_reason().is_none())
}

/// One entry of a kopia directory manifest (`kopia show <dir-object-id>`).
///
/// Files carry a top-level `size`; directories instead embed an aggregate
/// [`DirSummaryLite`] under `summ`. All fields beyond name/type/obj are
/// optional because kopia omits what doesn't apply to the entry type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirEntry {
    /// Entry name (a single path component, never a path).
    pub name: String,
    /// Entry type: `"d"` (directory), `"f"` (file), `"s"` (symlink).
    #[serde(rename = "type")]
    pub entry_type: String,
    /// The kopia object id backing the entry — a directory's `obj` can be
    /// `kopia show`n for the next manifest level; a file's streams its bytes.
    pub obj: String,
    /// File size in bytes (files only; directories report sizes via `summ`).
    #[serde(default)]
    pub size: Option<i64>,
    /// Modification time as kopia rendered it (RFC3339; kept as a string so an
    /// unusual kopia rendering can never fail the whole manifest parse).
    #[serde(default)]
    pub mtime: Option<String>,
    /// Unix permission bits as an octal string (e.g. `"0755"`).
    #[serde(default)]
    pub mode: Option<String>,
    /// Aggregate subtree summary (directories only).
    #[serde(default)]
    pub summ: Option<DirSummaryLite>,
}

/// The aggregate subtree counters under a directory entry's `summ` block —
/// the subset of [`DirSummary`] a directory listing renders. All optional:
/// kopia may extend or omit counters across releases.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirSummaryLite {
    /// Total logical size of the subtree in bytes.
    #[serde(default)]
    pub size: Option<i64>,
    /// Number of files in the subtree.
    #[serde(default)]
    pub files: Option<i64>,
    /// Number of directories in the subtree.
    #[serde(default)]
    pub dirs: Option<i64>,
}

/// A kopia directory manifest: what `kopia show <dir-object-id>` emits —
/// `{"stream":"kopia:directory","entries":[…]}`. (`kopia show` on a *file*
/// object streams the file's raw bytes instead, so callers must check
/// [`DirEntry::entry_type`] before showing an object as a directory.)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirManifest {
    /// The manifest stream marker; `"kopia:directory"` for directory objects.
    pub stream: String,
    /// The directory's entries, in kopia's on-manifest order.
    #[serde(default)]
    pub entries: Vec<DirEntry>,
}

/// Client identity options reported by `kopia repository status`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ClientOptions {
    /// The configured hostname for this client.
    #[serde(default)]
    pub hostname: String,
    /// The configured username for this client.
    #[serde(default)]
    pub username: String,
    /// Human-readable repository description.
    #[serde(default)]
    pub description: String,
    /// Whether snapshot actions are enabled.
    #[serde(default)]
    pub enable_actions: bool,
}

/// Storage backend block from `kopia repository status`. `config` is left as a
/// raw JSON value because its shape is backend-specific (filesystem path vs S3
/// bucket/endpoint vs ...).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StorageInfo {
    /// Backend type, e.g. "filesystem", "s3", "gcs".
    #[serde(default, rename = "type")]
    pub storage_type: String,
    /// Backend-specific configuration, opaque here.
    #[serde(default)]
    pub config: serde_json::Value,
}

/// Content format block from `kopia repository status`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ContentFormat {
    /// Hash algorithm, e.g. "BLAKE2B-256-128".
    #[serde(default)]
    pub hash: String,
    /// Encryption algorithm, e.g. "AES256-GCM-HMAC-SHA256".
    #[serde(default)]
    pub encryption: String,
    /// Repository format version.
    #[serde(default)]
    pub version: u32,
    /// Epoch-manager parameters, when the repository uses the epoch index (format v2+).
    /// Absent on older formats, hence `Option`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub epoch_parameters: Option<EpochParameters>,
}

/// kopia's epoch-manager parameters, as reported inside
/// `repository status --json` → `contentFormat.epochParameters`.
///
/// **This block does not follow the `rename_all = "camelCase"` convention the rest of this
/// module uses** — kopia serializes the Go struct's field names verbatim, so the keys are
/// PascalCase with no consistent rule between them (`MinEpochDuration` vs
/// `EpochRefreshFrequency` vs `FullCheckpointFrequency` vs `DeleteParallelism`). Hence the
/// explicit per-field renames; `crates/kopia/tests/fixtures/repository_status.json` carries
/// real kopia 0.23 output and pins the shape.
///
/// Units are Go-native and not what the flag names suggest:
/// - durations are `time.Duration` **nanoseconds** (as [`MaintenanceCadence::interval`] is);
/// - `EpochAdvanceOnTotalSizeBytesThreshold` is **bytes**, and the `--epoch-advance-on-size-mb`
///   flag that sets it means **MiB** — `7` yields `7340032` (7 × 1048576), even though kopia's
///   own log line renders it as "7.3 MB".
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct EpochParameters {
    /// Whether the epoch manager is enabled on this repository.
    #[serde(rename = "Enabled", default)]
    pub enabled: bool,
    /// Minimum epoch age before it may advance, in nanoseconds (kopia default 24h).
    #[serde(rename = "MinEpochDuration", default)]
    pub min_epoch_duration_ns: i64,
    /// How often clients re-read epoch state, in nanoseconds (kopia default 20m).
    #[serde(rename = "EpochRefreshFrequency", default)]
    pub epoch_refresh_frequency_ns: i64,
    /// Grace window protecting index blobs a concurrent writer may still need, in
    /// nanoseconds (kopia default 4h).
    #[serde(rename = "CleanupSafetyMargin", default)]
    pub cleanup_safety_margin_ns: i64,
    /// Index-blob count that triggers an epoch advance (kopia default 20).
    #[serde(rename = "EpochAdvanceOnCountThreshold", default)]
    pub advance_on_count: i64,
    /// Total index size in **bytes** that triggers an epoch advance (kopia default 10 MiB).
    #[serde(rename = "EpochAdvanceOnTotalSizeBytesThreshold", default)]
    pub advance_on_total_size_bytes: i64,
    /// Epochs between full index checkpoints (kopia default 7).
    #[serde(rename = "FullCheckpointFrequency", default)]
    pub checkpoint_frequency: i64,
    /// Parallelism for epoch-cleanup deletions (kopia default 4).
    #[serde(rename = "DeleteParallelism", default)]
    pub delete_parallelism: i64,
}

/// Result of `kopia repository status --json`.
///
/// The repository's stable identity is `uniqueIDHex` (kopia's JSON key, hence
/// the explicit rename). We keep the high-value fields typed and leave the rest
/// (volume capacity, object format, epoch params) for future expansion without
/// breaking on unknown fields.
///
/// Parse a trimmed status object — note the `uniqueIDHex` key maps to
/// `unique_id_hex`, and unknown fields (here `extraFutureField`) are tolerated:
///
/// ```
/// use kopiur_kopia::RepositoryStatus;
///
/// let json = r#"{
///     "configFile": "/config/repository.config",
///     "uniqueIDHex": "deadbeef",
///     "clientOptions": {"hostname": "prod", "username": "mydb"},
///     "storage": {"type": "s3", "config": {"bucket": "backups"}},
///     "contentFormat": {"hash": "BLAKE2B-256-128", "encryption": "AES256-GCM-HMAC-SHA256", "version": 3},
///     "extraFutureField": 42
/// }"#;
/// let status: RepositoryStatus = serde_json::from_str(json).unwrap();
/// assert_eq!(status.unique_id_hex, "deadbeef");
/// assert_eq!(status.storage.storage_type, "s3");
/// assert_eq!(status.content_format.version, 3);
/// assert_eq!(status.client_options.username, "mydb");
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RepositoryStatus {
    /// Path to the local repository config file.
    #[serde(default)]
    pub config_file: String,
    /// The repository's stable unique id. kopia's key is `uniqueIDHex`.
    #[serde(default, rename = "uniqueIDHex")]
    pub unique_id_hex: String,
    /// Client identity options.
    pub client_options: ClientOptions,
    /// Storage backend info.
    pub storage: StorageInfo,
    /// Content format (hash/encryption/version).
    pub content_format: ContentFormat,
    /// Object-lock blob retention, from kopia's `kopia.blobcfg` blob.
    ///
    /// **Top-level**, unlike the epoch parameters nested under `contentFormat` — do not
    /// follow that pattern here. `omitempty` on both inner keys means kopia emits `{}` when
    /// retention is off, so an all-default value is the "disabled" observation, not a
    /// missing one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub blob_retention: Option<BlobRetention>,
}

/// Blob retention as reported by `kopia repository status --json` → `blobRetention`.
///
/// Mirrors kopia's `format.BlobStorageConfiguration`. Unlike the sibling [`EpochParameters`],
/// the keys here **are** camelCase (kopia gives that struct explicit JSON tags), and unlike
/// it this type cannot be `Copy` — it carries a `String`.
///
/// `retentionPeriod` is a Go `time.Duration`, so the unit is **nanoseconds** (the same
/// convention as [`MaintenanceCadence::interval`]), not seconds.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlobRetention {
    /// `GOVERNANCE`, `COMPLIANCE`, or empty when retention is off.
    #[serde(rename = "retentionMode", default)]
    pub mode: String,
    /// Retention period in **nanoseconds**; `0` when retention is off.
    #[serde(rename = "retentionPeriod", default)]
    pub period_ns: i64,
}

impl BlobRetention {
    /// Whether retention is actually in force. Mirrors kopia's own `IsRetentionEnabled()`:
    /// a non-empty mode AND a non-zero period — kopia treats a half-set config as off.
    pub fn is_enabled(&self) -> bool {
        !self.mode.is_empty() && self.period_ns != 0
    }
}

/// A maintenance cadence block (`quick` / `full`) from `maintenance info`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceCadence {
    /// Whether this maintenance class is enabled.
    #[serde(default)]
    pub enabled: bool,
    /// Interval between runs, in nanoseconds (kopia's Go `time.Duration`).
    #[serde(default)]
    pub interval: i64,
}

/// The `schedule` block: when maintenance next runs, plus the per-task run
/// history kopia keeps in the same blob.
///
/// `runs` is kopia's `map[TaskType][]RunInfo`
/// (`repo/maintenance/maintenance_schedule.go`). It carries **no** `omitempty`,
/// so a repository that has never run maintenance emits `"runs": null` rather
/// than omitting the key — hence [`Self::runs`] must tolerate an explicit null,
/// which `#[serde(default)]` alone does NOT (a default applies only to an
/// ABSENT key). See the field for the deserializer that does.
///
/// kopia's `Schedule.ReportRun` **prepends** each new run and truncates the
/// history to 50 entries per task. Never key a before/after comparison on index
/// or length: at saturation `len(after) == len(before)`. Compare
/// [`MaintenanceRun::start`] instead — that is what
/// [`reclaimed_bytes_since`] does.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceSchedule {
    /// Next scheduled full maintenance, if known.
    #[serde(default)]
    pub next_full_maintenance: Option<DateTime<Utc>>,
    /// Next scheduled quick maintenance, if known.
    #[serde(default)]
    pub next_quick_maintenance: Option<DateTime<Utc>>,
    /// Per-task run history, newest first, capped at 50 entries per task.
    ///
    /// The key is kopia's `TaskType` string (`full-delete-blobs`,
    /// `snapshot-gc`, …) — see the `TASK_*` constants. A `BTreeMap` (not a
    /// typed enum) on purpose: a newer kopia adding a task must not fail the
    /// parse of a `maintenance info` the mover's lease decision depends on.
    ///
    /// `deserialize_with` is not decoration: `#[serde(default)]` alone rejects
    /// the explicit `"runs": null` a fresh repository really emits (proven by
    /// `null_runs_history_decodes_as_empty`), because a default only applies to
    /// an ABSENT key.
    #[serde(default, deserialize_with = "null_as_default")]
    pub runs: BTreeMap<String, Vec<MaintenanceRun>>,
}

/// Deserialize an explicit JSON `null` as `T::default()` rather than an error.
///
/// Needed wherever kopia's Go struct field carries no `omitempty` but its value
/// is a nil map/slice: `encoding/json` writes `null`, and serde's `default`
/// covers only a MISSING key.
fn null_as_default<'de, D, T>(d: D) -> Result<T, D::Error>
where
    D: serde::Deserializer<'de>,
    T: Default + Deserialize<'de>,
{
    Ok(Option::<T>::deserialize(d)?.unwrap_or_default())
}

/// kopia maintenance task: delete blobs no index references, in a **quick** run.
/// The `deletedTotalSize` its [`TASK_DELETE_UNREFERENCED_PACKS_STATS`] extra
/// reports is storage actually freed from the backend.
pub const TASK_QUICK_DELETE_BLOBS: &str = "quick-delete-blobs";
/// kopia maintenance task: the [`TASK_QUICK_DELETE_BLOBS`] twin in a **full** run.
pub const TASK_FULL_DELETE_BLOBS: &str = "full-delete-blobs";
/// kopia maintenance task: drop index blobs superseded by epoch compaction.
pub const TASK_DELETE_SUPERSEDED_EPOCH_INDEXES: &str = "delete-superseded-epoch-indexes";
/// kopia maintenance task: expire old repository log blobs per `logRetention`.
pub const TASK_CLEANUP_LOGS: &str = "cleanup-logs";

/// `extra[].kind` for [`DeleteUnreferencedPacksStats`].
pub const TASK_DELETE_UNREFERENCED_PACKS_STATS: &str = "deleteUnreferencedPacksStats";
/// `extra[].kind` for [`CleanupSupersededIndexesStats`].
pub const KIND_CLEANUP_SUPERSEDED_INDEXES_STATS: &str = "cleanupSupersededIndexesStats";
/// `extra[].kind` for [`CleanupLogsStats`].
pub const KIND_CLEANUP_LOGS_STATS: &str = "cleanupLogsStats";

/// One entry in a per-task maintenance run history (`schedule.runs[task][]`).
///
/// Mirrors kopia's `maintenance.RunInfo`. Two serialization details are
/// load-bearing:
///
/// * `success` is `json:"success,omitempty"`, so a **failed** run serializes
///   with the key *absent*. `#[serde(default)]` therefore decodes a failed run
///   as `success: false` — the same value kopia meant.
/// * `extra` is populated only on success, so a failed run contributes no
///   statistics at all.
///
/// `start`/`end` carry no `omitempty` in kopia today, but are modelled as
/// `Option` anyway: this history feeds a best-effort *metric*, and it must
/// never be the reason a `maintenance info` — which the mover's lease decision
/// depends on — fails to parse.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceRun {
    /// When the run started. The only sound key for a before/after comparison
    /// (see [`MaintenanceSchedule::runs`] on why index and length are not).
    #[serde(default)]
    pub start: Option<DateTime<Utc>>,
    /// When the run finished.
    #[serde(default)]
    pub end: Option<DateTime<Utc>>,
    /// Whether the run succeeded. Absent on the wire means `false`.
    #[serde(default)]
    pub success: bool,
    /// kopia's failure text, empty on success.
    #[serde(default)]
    pub error: String,
    /// Per-task statistics blocks; populated only on success.
    #[serde(default)]
    pub extra: Vec<MaintenanceRunExtra>,
}

impl MaintenanceRun {
    /// The typed `data` of the first extra with `kind`, or `None` when this run
    /// carries no such extra (or its `data` does not fit `T` — kopia emits an
    /// explicit `"data": null` for the statless tasks).
    fn stats<T: serde::de::DeserializeOwned>(&self, kind: &str) -> Option<T> {
        self.extra
            .iter()
            .find(|e| e.kind == kind)
            .and_then(|e| serde_json::from_value(e.data.clone()).ok())
    }

    /// Blobs deleted because no index referenced them — the one statistic that
    /// reports storage genuinely freed from the backend.
    pub fn delete_unreferenced_packs_stats(&self) -> Option<DeleteUnreferencedPacksStats> {
        self.stats(TASK_DELETE_UNREFERENCED_PACKS_STATS)
    }

    /// Index blobs deleted after epoch compaction superseded them.
    pub fn cleanup_superseded_indexes_stats(&self) -> Option<CleanupSupersededIndexesStats> {
        self.stats(KIND_CLEANUP_SUPERSEDED_INDEXES_STATS)
    }

    /// Repository log blobs deleted per `logRetention`.
    pub fn cleanup_logs_stats(&self) -> Option<CleanupLogsStats> {
        self.stats(KIND_CLEANUP_LOGS_STATS)
    }
}

/// One statistics block on a [`MaintenanceRun`] — kopia's
/// `maintenancestats.Extra`, which is `{Kind string; Data json.RawMessage}`.
///
/// `data` is a **nested object** whose shape depends on `kind`, so this is
/// deliberately *not* a `#[serde(tag = ...)]` enum: an unknown `kind` written
/// by a newer kopia must still decode (and kopia emits `"data": null` for the
/// tasks that have no statistics, which a tagged enum would also reject). Reach
/// for the typed accessors on [`MaintenanceRun`] instead of matching on `kind`
/// by hand.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MaintenanceRunExtra {
    /// kopia's statistics-kind discriminator, e.g. `deleteUnreferencedPacksStats`.
    #[serde(default)]
    pub kind: String,
    /// The kind-specific payload; `null` for the statless tasks.
    #[serde(default)]
    pub data: serde_json::Value,
}

/// `deleteUnreferencedPacksStats` — the `quick-delete-blobs` /
/// `full-delete-blobs` result. **This** is where reclaimed storage is reported:
/// the task issues real blob deletes against the backend.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DeleteUnreferencedPacksStats {
    /// Pack blobs found unreferenced by any index.
    #[serde(default)]
    pub unreferenced_pack_count: i64,
    /// Total bytes of those unreferenced pack blobs.
    #[serde(default)]
    pub unreferenced_total_size: i64,
    /// Pack blobs actually deleted this run.
    #[serde(default)]
    pub deleted_pack_count: i64,
    /// **Bytes actually freed from the backend** this run.
    #[serde(default)]
    pub deleted_total_size: i64,
    /// Pack blobs held back by the run's safety margin (too recent to delete).
    #[serde(default)]
    pub retained_pack_count: i64,
    /// Total bytes of the retained pack blobs.
    #[serde(default)]
    pub retained_total_size: i64,
}

/// `cleanupSupersededIndexesStats` — the `delete-superseded-epoch-indexes`
/// result. Real blob deletes, so its `deletedTotalSize` is freed storage too.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CleanupSupersededIndexesStats {
    /// Index blobs deleted this run.
    #[serde(default)]
    pub deleted_blob_count: i64,
    /// Bytes freed by deleting them.
    #[serde(default)]
    pub deleted_total_size: i64,
}

/// `cleanupLogsStats` — the `cleanup-logs` result. Repository log blobs are real
/// blobs, so `deletedBlobSize` is freed storage as well (a small figure, but a
/// true one).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CleanupLogsStats {
    /// Log blobs eligible for deletion.
    #[serde(default)]
    pub to_delete_blob_count: i64,
    /// Total bytes of the eligible log blobs.
    #[serde(default)]
    pub to_delete_blob_size: i64,
    /// Log blobs actually deleted this run.
    #[serde(default)]
    pub deleted_blob_count: i64,
    /// Bytes freed by deleting them.
    #[serde(default)]
    pub deleted_blob_size: i64,
    /// Log blobs kept.
    #[serde(default)]
    pub retained_blob_count: i64,
    /// Total bytes of the kept log blobs.
    #[serde(default)]
    pub retained_blob_size: i64,
}

/// Result of `kopia maintenance info --json`.
///
/// `interval` is kopia's Go `time.Duration` in nanoseconds; the `schedule` block
/// is optional:
///
/// ```
/// use kopiur_kopia::MaintenanceInfo;
///
/// let json = r#"{
///     "owner": "mydb@prod",
///     "quick": {"enabled": true, "interval": 3600000000000},
///     "full": {"enabled": false, "interval": 0}
/// }"#;
/// let info: MaintenanceInfo = serde_json::from_str(json).unwrap();
/// assert_eq!(info.owner, "mydb@prod");
/// assert!(info.quick.enabled);
/// assert_eq!(info.quick.interval, 3_600_000_000_000); // 1h in nanos
/// assert!(!info.full.enabled);
/// assert!(info.schedule.is_none());
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceInfo {
    /// The `user@host` that owns the maintenance lease.
    #[serde(default)]
    pub owner: String,
    /// Quick maintenance cadence.
    pub quick: MaintenanceCadence,
    /// Full maintenance cadence.
    pub full: MaintenanceCadence,
    /// Schedule with next-run timestamps.
    #[serde(default)]
    pub schedule: Option<MaintenanceSchedule>,
}

/// The newest [`MaintenanceRun::start`] recorded for `task`, or `None` when the
/// schedule has no successful-or-failed entry for it.
fn newest_run_start(info: &MaintenanceInfo, task: &str) -> Option<DateTime<Utc>> {
    info.schedule
        .as_ref()?
        .runs
        .get(task)?
        .iter()
        .filter_map(|r| r.start)
        .max()
}

/// The **successful** runs of `task` present in `after` but not in `before`.
///
/// Selected by `start` strictly newer than the newest `start` `before` had for
/// that task — never by index or length, because kopia prepends and caps the
/// history at 50 entries per task, so at saturation the two lists are the same
/// length (see [`MaintenanceSchedule::runs`]). A run with no `start` cannot be
/// proven new and is skipped.
fn runs_since<'a>(
    before: &'a MaintenanceInfo,
    after: &'a MaintenanceInfo,
    task: &'a str,
) -> impl Iterator<Item = &'a MaintenanceRun> {
    let floor = newest_run_start(before, task);
    after
        .schedule
        .iter()
        .filter_map(move |s| s.runs.get(task))
        .flatten()
        .filter(move |r| r.success && r.start.is_some_and(|start| floor.is_none_or(|f| start > f)))
}

/// Bytes of backend storage **actually freed** by the maintenance run that
/// happened between two `kopia maintenance info` observations.
///
/// `kopia maintenance run` prints no machine-readable result, so the only way to
/// learn what a run reclaimed is to diff the per-task run history it appends to
/// the schedule blob. Returns `None` when no counted task produced a new
/// successful run — the honest answer for an epoch-enabled repository's *quick*
/// run, which kopia short-circuits into `compact-single-epoch` + `advance-epoch`
/// only (`runQuickMaintenance`), neither of which deletes a blob. `Some(0)`
/// means a counted task *did* run and freed nothing; `None` means unknown. They
/// are never conflated.
///
/// # What is counted, and what deliberately is not
///
/// Counted, because each issues real blob deletes against the backend:
///
/// | task | statistic |
/// |---|---|
/// | `quick-delete-blobs`, `full-delete-blobs` | [`DeleteUnreferencedPacksStats::deleted_total_size`] |
/// | `delete-superseded-epoch-indexes` | [`CleanupSupersededIndexesStats::deleted_total_size`] |
/// | `cleanup-logs` | [`CleanupLogsStats::deleted_blob_size`] |
///
/// **Not** counted: `snapshotGCStats.deletedContentSize`, however tempting its
/// name. `snapshot-gc` only *marks* contents deleted in the index
/// (`snapshot/snapshotgc/gc.go`) and frees no storage at all — the blobs still
/// occupy the bucket until a later `*-delete-blobs` removes them. Reporting it
/// would show tens of gigabytes "reclaimed" while the bucket did not shrink by
/// a byte. `rewriteContentsStats` is excluded for the mirror-image reason: it
/// *writes* new packs and orphans the old ones, so its bytes are moved, not
/// freed.
pub fn reclaimed_bytes_since(before: &MaintenanceInfo, after: &MaintenanceInfo) -> Option<i64> {
    let mut total = 0i64;
    let mut measured = false;
    // `saturating_add`, not `+=`: the summands come from kopia's `extra[].data`,
    // which is an untyped JSON object this crate does not validate. A release
    // build would WRAP an overflowing sum into a negative "reclaimed" figure —
    // a number worse than no number at all on a backup operator.
    let mut add = |bytes: i64| {
        measured = true;
        total = total.saturating_add(bytes);
    };
    for task in [TASK_QUICK_DELETE_BLOBS, TASK_FULL_DELETE_BLOBS] {
        for run in runs_since(before, after, task) {
            add(run
                .delete_unreferenced_packs_stats()
                .map_or(0, |s| s.deleted_total_size));
        }
    }
    for run in runs_since(before, after, TASK_DELETE_SUPERSEDED_EPOCH_INDEXES) {
        add(run
            .cleanup_superseded_indexes_stats()
            .map_or(0, |s| s.deleted_total_size));
    }
    for run in runs_since(before, after, TASK_CLEANUP_LOGS) {
        add(run.cleanup_logs_stats().map_or(0, |s| s.deleted_blob_size));
    }
    measured.then_some(total)
}

/// One entry from `kopia index list --json` — a single content-index blob.
///
/// kopia's index is a set of these blobs; periodic maintenance compacts them.
/// When maintenance stops running (e.g. a stale lease owner), the count grows
/// unbounded and kopia eventually warns "Found too many index blobs (N)". We
/// only need the COUNT (the length of the array), so we keep just enough fields
/// to make a meaningful, future-proof model and let serde ignore the rest
/// (`timestamp`, `Superseded`, …).
///
/// ```
/// use kopiur_kopia::IndexBlobEntry;
///
/// let json = r#"{"id":"xn0_5ce…-c1","length":143,"timestamp":"2026-06-15T22:30:50Z","Superseded":null}"#;
/// let e: IndexBlobEntry = serde_json::from_str(json).unwrap();
/// assert_eq!(e.length, 143);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct IndexBlobEntry {
    /// The index blob's id (kopia's `id`, e.g. `xn0_…-c1`).
    #[serde(default)]
    pub id: String,
    /// On-disk length of the index blob in bytes.
    #[serde(default)]
    pub length: i64,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn entry_errors_parse_from_ignored_error_snapshot() {
        // The exact shape kopia 0.23.1 emits when ignore-file-errors is set: exit 0,
        // numFailed=0, but summ.errors[] still lists every skipped entry (verified
        // empirically against a uid-2000 0600 tree snapshotted as uid 65532).
        let json = r#"{
            "id": "k1",
            "source": {"host": "h", "userName": "u", "path": "/pvc"},
            "startTime": "2026-06-02T03:13:59Z",
            "endTime": "2026-06-02T03:14:00Z",
            "rootEntry": {
                "name": "pvc", "type": "d", "obj": "k1",
                "summ": {"size": 7, "files": 2, "dirs": 2, "numFailed": 0, "errors": [
                    {"path": "secret_dir", "error": "cannot create iterator: unable to read directory: open /pvc/secret_dir: permission denied"},
                    {"path": "topsecret.txt", "error": "unable to open file: open /pvc/topsecret.txt: permission denied"}
                ]}
            }
        }"#;
        let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
        // numFailed is 0 (errors were ignored by policy) — so the COUNT must come from
        // entry_errors(), not error_count(), or the incomplete snapshot stays silent.
        assert_eq!(r.error_count(), 0);
        assert_eq!(r.entry_errors().len(), 2);
        assert_eq!(r.entry_errors()[0].path, "secret_dir");
        assert!(r.entry_errors()[1].error.contains("permission denied"));
    }

    #[test]
    fn entry_errors_empty_on_clean_snapshot() {
        let json = r#"{
            "id": "k1", "source": {"host": "h", "userName": "u", "path": "/p"},
            "startTime": "2026-06-02T03:13:59Z", "endTime": "2026-06-02T03:14:00Z",
            "rootEntry": {"name": "p", "type": "d", "obj": "k1", "summ": {"size": 4096, "files": 12}}
        }"#;
        let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
        assert!(r.entry_errors().is_empty());
    }

    #[test]
    fn index_blob_list_counts_entries() {
        // The real shape emitted by `kopia index list --json` (verified against
        // kopia 0.23.0): a JSON array of entries. The count is the array length.
        let json = r#"[
            {"id":"xn0_aaa-c1","length":143,"timestamp":"2026-06-15T22:30:50.3-07:00","Superseded":null},
            {"id":"xn0_bbb-c1","length":201,"timestamp":"2026-06-15T22:31:01.1-07:00","Superseded":null}
        ]"#;
        let entries: Vec<IndexBlobEntry> = serde_json::from_str(json).unwrap();
        assert_eq!(entries.len(), 2);
        assert_eq!(entries[0].id, "xn0_aaa-c1");
        assert_eq!(entries[1].length, 201);
    }

    #[test]
    fn index_blob_list_empty_is_zero() {
        let entries: Vec<IndexBlobEntry> = serde_json::from_str("[]").unwrap();
        assert_eq!(entries.len(), 0);
    }

    #[test]
    fn snapshot_source_identity() {
        let s = SnapshotSource {
            host: "h".into(),
            user_name: "u".into(),
            path: "/p".into(),
        };
        assert_eq!(s.identity(), "u@h:/p");
    }

    // --- DirManifest: the EXACT `kopia show <dir-oid>` JSON shape, verified
    // against kopia 0.23. ---

    #[test]
    fn dir_manifest_parses_the_verified_kopia_show_shape() {
        let json = r#"{
            "stream": "kopia:directory",
            "entries": [
                {
                    "name": "sub",
                    "type": "d",
                    "mode": "0755",
                    "mtime": "2026-06-10T12:00:00Z",
                    "obj": "kdeadbeef",
                    "summ": {"size": 7, "files": 1, "dirs": 1, "maxTime": "2026-06-10T12:00:00Z"}
                },
                {
                    "name": "a.txt",
                    "type": "f",
                    "mode": "0644",
                    "size": 6,
                    "mtime": "2026-06-10T11:59:00Z",
                    "obj": "1f00dcafe"
                }
            ],
            "summary": {"size": 13, "files": 2, "dirs": 2}
        }"#;
        let m: DirManifest = serde_json::from_str(json).unwrap();
        assert_eq!(m.stream, "kopia:directory");
        assert_eq!(m.entries.len(), 2);

        // Directory entry: no top-level size, aggregate counters under summ.
        let dir = &m.entries[0];
        assert_eq!(dir.name, "sub");
        assert_eq!(dir.entry_type, "d");
        assert_eq!(dir.obj, "kdeadbeef");
        assert_eq!(dir.mode.as_deref(), Some("0755"));
        assert_eq!(dir.size, None);
        let summ = dir.summ.as_ref().expect("directory summ");
        assert_eq!(summ.size, Some(7));
        assert_eq!(summ.files, Some(1));
        assert_eq!(summ.dirs, Some(1));

        // File entry: top-level size, no summ.
        let file = &m.entries[1];
        assert_eq!(file.name, "a.txt");
        assert_eq!(file.entry_type, "f");
        assert_eq!(file.obj, "1f00dcafe");
        assert_eq!(file.size, Some(6));
        assert_eq!(file.mtime.as_deref(), Some("2026-06-10T11:59:00Z"));
        assert!(file.summ.is_none());
    }

    #[test]
    fn dir_manifest_tolerates_missing_entries_and_unknown_fields() {
        // An empty directory manifest has no `entries`; future kopia fields
        // (and the unmapped top-level `summary`) must not fail the parse.
        let m: DirManifest =
            serde_json::from_str(r#"{"stream": "kopia:directory", "futureField": 1}"#).unwrap();
        assert_eq!(m.stream, "kopia:directory");
        assert!(m.entries.is_empty());
    }
}