shepherd-registry 6.7.0

The shepherd registry: the SQLite schema, migration runner, and query surface that every harness reads directly.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

/*
    Appellation: error <module>
    Created At: 2026.08.12:16:20:00
    Contrib: @FL03
*/
//! Typed registry errors.
//!
//! `rusqlite::Error` is wrapped rather than leaked so that a consumer can match
//! on registry semantics (a migration failed, the schema is ahead of this
//! binary) without matching on SQLite internals.
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::string::{String, ToString};

/// The result type returned throughout the registry.
pub type Result<T = (), E = Error> = core::result::Result<T, E>;

/// Every failure the registry itself can produce.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// The engine reported a domain failure.
    #[error(transparent)]
    Core(#[from] shepherd_core::Error),
    /// SQLite reported a failure.
    #[error(transparent)]
    Sqlite(#[from] rusqlite::Error),
    /// The host filesystem rejected a bounded custody operation.
    #[cfg(feature = "std")]
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// A migration failed to apply; carries the version that broke.
    #[error("migration {version} failed: {message}")]
    Migration { version: i64, message: String },
    /// A recorded migration checksum no longer matches the embedded SQL.
    #[error(
        "registry corruption: migration {version} checksum mismatch: expected {expected}, found {found}; run `shepherd registry repair --confirm`"
    )]
    MigrationChecksum {
        version: i64,
        expected: String,
        found: String,
    },
    /// A migration row exists but its required catalog postcondition is absent.
    #[error(
        "registry corruption: migration {version} postcondition failed: {object}; run `shepherd registry repair --confirm`"
    )]
    MigrationPostcondition { version: i64, object: String },
    /// The schema ledger skips a version that this binary owns.
    #[error(
        "registry corruption: migration ledger gap at version {version}; run `shepherd registry repair --confirm`"
    )]
    MigrationGap { version: i64 },
    /// A schema ledger row names a migration this binary does not own.
    #[error(
        "registry corruption: unknown migration version {version}; run `shepherd registry repair --confirm`"
    )]
    UnknownMigration { version: i64 },
    /// A repair was refused because the database is not an exact replayable
    /// missing-migration state.
    #[error("registry repair refused: {0}")]
    RepairRefused(String),
    /// A repair or rollback receipt could not be validated.
    #[error("registry receipt is invalid: {0}")]
    InvalidReceipt(String),
    /// Restoring a live file failed and compensation from the retained guard
    /// also failed. Guard artifacts remain the recovery source.
    #[error(
        "rollback failed ({cause}); compensation failed ({compensation}); guard evidence preserved"
    )]
    RollbackCompensation { cause: String, compensation: String },
    /// A singleton publication request is malformed or cannot be replayed safely.
    #[error("invalid singleton publication: {0}")]
    InvalidSingletonPublication(String),
    /// A singleton publication was found in a conflicting durable state.
    #[error("singleton publication conflict for nonce `{nonce}`: {reason}")]
    SingletonPublicationConflict { nonce: String, reason: String },
    /// The database schema is newer than this binary understands.
    #[error("registry schema version {found} is ahead of the supported {supported}")]
    SchemaAhead { found: i64, supported: i64 },
    /// A mutating operation was requested through a read-only registry.
    #[error("registry is read-only")]
    ReadOnly,
    /// A run/lane singleton already has a different native owner.
    #[error(
        "dispatch singleton claim conflict for {project_id}/{run_id}/{role}/{lane_key}; existing agent `{agent_id}`"
    )]
    DispatchClaimConflict {
        project_id: String,
        run_id: String,
        role: String,
        lane_key: String,
        agent_id: String,
    },
    /// A singleton claim request does not describe a valid logical identity.
    #[error("invalid dispatch singleton claim: {0}")]
    InvalidDispatchClaim(String),
    /// The registry path would cross a symbolic-link boundary.
    #[error("unsafe registry path: {0}")]
    UnsafePath(String),
    /// Rolling back a failed transaction also failed.
    #[error("transaction failed ({cause}) and rollback failed ({rollback})")]
    TransactionRollback { cause: String, rollback: String },
    /// A catch-all for registry failures that do not yet warrant a variant.
    #[error("{0}")]
    Unknown(String),
}

impl Error {
    /// Build an [`Error::Unknown`] from anything displayable.
    pub fn unknown(message: impl core::fmt::Display) -> Self {
        Self::Unknown(message.to_string())
    }
}