sysknife_types/

lib.rs

use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::convert::TryFrom;

use sysknife_proto::sysknife::v1 as proto;

// ---------------------------------------------------------------------------
// Framing / wire protocol
// ---------------------------------------------------------------------------

/// Maximum size of a single message exchanged over a sysknife socket, in bytes
/// (4 MiB).
///
/// As a wire fact, the frame limit belongs to the protocol crate that every
/// side already depends on, rather than to any one executor (the daemon), so
/// that the daemon and the CLI agree on it without a dependency edge from a
/// consumer up to a privileged producer. Duplicate declarations of the limit
/// elsewhere are guarded against by `tests::frame_limit_is_declared_once`.
pub const MAX_MESSAGE_BYTES: usize = 4 * 1024 * 1024;

// ---------------------------------------------------------------------------
// DistroHint — planner-facing snapshot of the running distro
// ---------------------------------------------------------------------------

/// Planner-facing distro snapshot injected into the system prompt.
///
/// This is a deliberately lightweight type: it captures only what the planner
/// needs to pick the right action family (`family`), distinguish Ubuntu-only
/// mechanisms (`id`), and produce human-readable output (`version`). Detection and the full
/// `DistroId` enum stay in `sysknife-core`; the CLI converts `DistroId` →
/// `DistroHint` at startup so the brain never depends on `sysknife-core`.
///
/// # Design rationale
///
/// Moving `DistroId` to `sysknife-types` would add proto-bridge boilerplate
/// and force every crate that imports types to compile the detection logic.
/// A thin snapshot type is smaller-diff and still gives the planner everything
/// it needs.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct DistroHint {
    /// Detected distribution ID, e.g. `ubuntu` or `debian`. Family membership
    /// alone cannot authorize an Ubuntu-only mechanism. Never derive this from
    /// the human-readable version string.
    pub id: String,
    /// Broad distro family: `"fedora"`, `"debian"`, or `"other"`.
    ///
    /// Use `DISTRO_FAMILY_FEDORA`, `DISTRO_FAMILY_DEBIAN`, and
    /// `DISTRO_FAMILY_OTHER` for comparison to avoid magic strings.
    pub family: &'static str,
    /// Human-readable version string, e.g. `"Fedora 41"`, `"Ubuntu 24.04"`.
    /// `None` when the version could not be determined.
    pub version: Option<String>,
}

/// Family label for Fedora-family distros (Fedora, FedoraSilverblue, etc.).
pub const DISTRO_FAMILY_FEDORA: &str = "fedora";

/// Family label for Debian-family distros (Ubuntu, Debian, etc.).
pub const DISTRO_FAMILY_DEBIAN: &str = "debian";

/// Family label for distros that do not fit into a known family.
pub const DISTRO_FAMILY_OTHER: &str = "other";

// ---------------------------------------------------------------------------
// ActionName — validated action catalogue primitive
// ---------------------------------------------------------------------------

/// Canonical names of every action in the SysKnife catalogue.
///
/// This is the single source of truth for "is this string a valid action
/// name?" — kept in `sysknife-types` (not `sysknife-brain`) so every crate
/// that validates an action name (the daemon's `policy::min_role_for_action`,
/// the CLI's approval flow, the proto bridge) sees the same list without
/// depending on the brain.
///
/// Note: [`RequestEnvelope::action_name`] itself is a plain `String` — it is
/// **not** validated against this list at deserialization time; that would
/// require a custom `Deserialize` impl this type does not have. Validation
/// happens downstream, via [`ActionName::parse`] against the value once it
/// has been pulled out of the envelope (the daemon does this before acting
/// on a request).
///
/// **Cross-module invariant:** `sysknife_brain::propose_plan::KNOWN_ACTIONS`
/// (which pairs each name with an LLM-facing description) MUST list every
/// name that appears here, in either order.  The brain has a unit test
/// (`every_known_action_name_is_in_types`) that pins this — adding an
/// action requires a coordinated update to both lists.
pub const KNOWN_ACTION_NAMES: &[&str] = &[
    "GetSystemState",
    "CollectDiagnostics",
    "GetDeploymentHistory",
    "ListDeployments",
    "UpdateSystem",
    "CleanupDeployments",
    "RebootSystem",
    "RollbackDeployment",
    "GetKernelArguments",
    "PinDeployment",
    "UnpinDeployment",
    "RebaseSystem",
    "SetKernelArguments",
    "InstallFlatpak",
    "RemoveFlatpak",
    "UpdateFlatpak",
    "SearchFlatpakApps",
    "ListFlatpakRemotes",
    "ListInstalledFlatpaks",
    "AddFlatpakRemote",
    "RemoveFlatpakRemote",
    "GetFlatpakAppInfo",
    "ListToolboxes",
    "CreateToolbox",
    "RemoveToolbox",
    "GetLayeredPackages",
    "ResetLayeredPackageOverride",
    "GetPendingUpdates",
    "InstallPackages",
    "RemovePackages",
    "AddLayeredPackage",
    "RemoveLayeredPackage",
    "ReplaceLayeredPackage",
    "RemoveBasePackage",
    "ListServices",
    "ListTimers",
    "ReloadDaemon",
    "CreateScheduledJob",
    "StartService",
    "StopService",
    "RestartService",
    "ReloadService",
    "SetServiceEnabled",
    "MaskService",
    "UnmaskService",
    "GetServiceLogs",
    "GetServiceStatus",
    "GetServiceResourceLimits",
    "SetServiceResourceLimits",
    "GetFirewallState",
    "GetNetworkStatus",
    "GetListeningPorts",
    "ConfigureWifi",
    "SetDnsServers",
    "ConfigureFirewall",
    "GetDiskUsage",
    "ListProcesses",
    "SignalProcess",
    "GetMemoryInfo",
    "GetHostState",
    // Observability / journald (cross-distro)
    "GetJournalLog",
    "VacuumJournal",
    // Storage / LVM (cross-distro)
    "GetLvmReport",
    "ExtendLogicalVolume",
    "CreateLogicalVolume",
    "CreateLvSnapshot",
    // Kernel / sysctl (cross-distro)
    "GetSysctl",
    "SetSysctl",
    // Filesystem mounts / swap (cross-distro)
    "GetMounts",
    "AddMount",
    "RemoveMount",
    "AddSwap",
    "RemoveSwap",
    // Scoped sudoers.d (cross-distro)
    "GetSudoGrants",
    "GrantSudoAccess",
    "RevokeSudoAccess",
    // Log management (cross-distro)
    "GetLogrotateStatus",
    "ConfigureLogRotation",
    "RemoveLogRotation",
    "ConfigureRemoteSyslog",
    "RemoveRemoteSyslog",
    // PAM password policy (cross-distro)
    "GetPasswordAging",
    "SetPasswordAging",
    "SetPasswordPolicy",
    "SetAccountLockout",
    // auditd file-watch rules (cross-distro)
    "GetAuditRules",
    "AddAuditRule",
    "RemoveAuditRule",
    // certbot / ACME (cross-distro)
    "GetCertificates",
    "ObtainCertificate",
    "RenewCertificates",
    "GetDateTime",
    "SetHostname",
    "SetTimezone",
    "SetLocale",
    "SetNtp",
    "ListPackageRepositories",
    "AddPackageRepository",
    "RemovePackageRepository",
    "EnablePackageRepository",
    "DisablePackageRepository",
    "ListContainers",
    "CreateContainer",
    "StartContainer",
    "StopContainer",
    "RemoveContainer",
    "GetContainerInfo",
    "ListUsers",
    "ListGroups",
    "CreateUser",
    "DeleteUser",
    "AddUserToGroup",
    "RemoveUserFromGroup",
    "CreateGroup",
    "DeleteGroup",
    "LockUserAccount",
    "UnlockUserAccount",
    "GetAuthorizedKeys",
    "AddAuthorizedKey",
    "RemoveAuthorizedKey",
    "SetSshdOption",
    "ListJobHistory",
    // Ubuntu / apt
    "AptUpdate",
    "AptUpgrade",
    "AptInstall",
    "AptRemove",
    "AptPurge",
    "AptAutoremove",
    "AptHold",
    "AptUnhold",
    "AptSearch",
    "AptListInstalled",
    "AptShow",
    "AptListUpgradable",
    "AptHistoryList",
    "ConfigureUnattendedUpgrades",
    "GetAptPins",
    "SetAptPin",
    "RemoveAptPin",
    // Ubuntu / ppa
    "AddPpa",
    "RemovePpa",
    // Ubuntu / snap
    "SnapInstall",
    "SnapRemove",
    "SnapRefresh",
    "SnapHold",
    "SnapUnhold",
    "SnapList",
    "SnapInfo",
    "SnapRevert",
    "SnapClassicInstall",
    // Ubuntu / ufw
    "UfwEnable",
    "UfwDisable",
    "UfwAllow",
    "UfwDeny",
    "UfwReset",
    "UfwStatus",
    // Ubuntu / distrobox
    "DistroboxList",
    "DistroboxCreate",
    "DistroboxRemove",
    // Ubuntu / netplan
    "NetplanGetConfig",
    "NetplanApply",
    "NetplanSet",
    "NetplanGenerate",
    // Ubuntu / grub
    "GrubGetKargs",
    "GrubSetKargs",
    // Ubuntu / reboot
    "CheckPendingReboot",
    // Cross-distro / resolvectl (systemd-resolved)
    "ResolvectlStatus",
    "ResolvectlSetDns",
    // Ubuntu / apparmor
    "AppArmorStatus",
    "AppArmorEnforce",
    "AppArmorComplain",
    // Ubuntu / cloud-init
    "CloudInitStatus",
    // Ubuntu / flatpak (Ubuntu-specific routing)
    "UbuntuInstallFlatpak",
    "UbuntuRemoveFlatpak",
    "UbuntuUpdateFlatpak",
    "UbuntuListFlatpaks",
    // Ubuntu / fail2ban
    "Fail2banStatus",
    "Fail2banBanIp",
    "Fail2banUnbanIp",
    "ConfigureFail2banJail",
    // Ubuntu / release upgrade (Tier 3)
    "UbuntuReleaseUpgrade",
    // Ubuntu / Ubuntu Pro (Tier 3)
    "ProStatus",
    "ProAttach",
    "ProDetach",
    "EnableProService",
    "DisableProService",
    // Ubuntu / Livepatch (Tier 3)
    "LivepatchStatus",
    // Ubuntu / Multipass (Tier 3)
    "MultipassList",
    // Ubuntu / ufw Tier 3
    "UfwDeleteRule",
    "UfwLimit",
];

/// A validated action name from the approved SysKnife catalogue.
///
/// Constructed via [`ActionName::parse`], which rejects any string not in
/// [`KNOWN_ACTION_NAMES`].  Holding an `ActionName` is a compile-time
/// guarantee that the contained string is in the catalogue — downstream
/// code does not need to re-validate.
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(transparent)]
pub struct ActionName(String);

impl ActionName {
    /// Parse a string into a validated `ActionName`.
    pub fn parse(name: impl Into<String>) -> Result<Self, UnknownActionName> {
        let name = name.into();
        if KNOWN_ACTION_NAMES.contains(&name.as_str()) {
            Ok(Self(name))
        } else {
            Err(UnknownActionName(name))
        }
    }

    /// Return the inner string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for ActionName {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

impl AsRef<str> for ActionName {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

/// Returned by [`ActionName::parse`] when the string is not a known action.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct UnknownActionName(pub String);

impl std::fmt::Display for UnknownActionName {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "unknown action name: '{}'", self.0)
    }
}

impl std::error::Error for UnknownActionName {}

// ---------------------------------------------------------------------------
// Request hash newtype
// ---------------------------------------------------------------------------

/// Hex-encoded SHA-256 hash of a [`RequestEnvelope`].
///
/// `serde(transparent)` keeps the wire format identical to a bare string so
/// existing JSON IPC frames deserialize unchanged.
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RequestHash(String);

impl RequestHash {
    pub fn new(s: impl Into<String>) -> Self {
        Self(s.into())
    }
    pub fn as_str(&self) -> &str {
        &self.0
    }
    pub fn into_inner(self) -> String {
        self.0
    }
}

impl std::fmt::Display for RequestHash {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

impl AsRef<str> for RequestHash {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl From<String> for RequestHash {
    fn from(s: String) -> Self {
        Self(s)
    }
}

// ---------------------------------------------------------------------------
// Approval-flow newtypes
// ---------------------------------------------------------------------------

/// Identifier for one preview/approve/execute round-trip.
///
/// Distinct from [`ApprovalReceipt`] at the type level because the two are
/// indistinguishable at the value level: both are opaque strings passed side by
/// side into the same calls. `execute(transaction_id, action_name, params,
/// approval_receipt, …)` took three bare `&str` in a row, so transposing any
/// two of them compiled and failed at runtime as a stale-approval error, which
/// reads like an expiry rather than a call-site bug.
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct TransactionId(String);

/// A one-time bearer receipt minted by `sysknife approve`.
///
/// This is a **credential**: whoever holds it can execute the approved step
/// once. `Debug` is redacted so a `tracing::debug!("{req:?}")` on any struct
/// carrying one cannot spill it into a log. Use [`ApprovalReceipt::as_str`]
/// where the real value is genuinely needed.
#[derive(Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ApprovalReceipt(String);

impl std::fmt::Debug for ApprovalReceipt {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("ApprovalReceipt(<redacted>)")
    }
}

macro_rules! opaque_string_newtype {
    ($name:ident) => {
        impl $name {
            pub fn new(s: impl Into<String>) -> Self {
                Self(s.into())
            }
            pub fn as_str(&self) -> &str {
                &self.0
            }
            pub fn into_inner(self) -> String {
                self.0
            }
        }

        impl AsRef<str> for $name {
            fn as_ref(&self) -> &str {
                &self.0
            }
        }

        impl From<String> for $name {
            fn from(s: String) -> Self {
                Self(s)
            }
        }
    };
}

opaque_string_newtype!(TransactionId);
opaque_string_newtype!(ApprovalReceipt);

// `Display` only for the identifier. `ApprovalReceipt` deliberately has none:
// a credential that formats itself into any `{}` is one interpolation away
// from a log line, and the explicit `as_str()` marks the places that really
// need the secret.
impl std::fmt::Display for TransactionId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

/// Caller privilege tier, ordered least to most privileged.
///
/// **Variant order is the privilege order** and `Ord` is derived from it, so
/// `caller >= required` is the authorization comparison. This mirrors what
/// v0.2.10 did for `PlanRiskLevel`; `CallerRole` kept a hand-written
/// `role_rank` match until now, which is a second encoding of the same
/// ordering that could drift from this declaration.
///
/// Adding a variant means placing it at the correct privilege position, not
/// appending it.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CallerRole {
    Observer,
    Dev,
    Admin,
    Boot,
}

impl CallerRole {
    /// Stable lowercase spelling, identical to the serde representation.
    ///
    /// The audit chain signs this string, so it is a wire format: renaming a
    /// variant must not silently change what past signatures were made over.
    /// `format!("{role:?}")` cannot be used for that — `Debug` carries no
    /// stability promise and tracks the identifier. `caller_role_as_str_matches_serde`
    /// pins the two encodings together.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Observer => "observer",
            Self::Dev => "dev",
            Self::Admin => "admin",
            Self::Boot => "boot",
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RiskLevel {
    Low,
    Medium,
    High,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum JobState {
    Queued,
    Running,
    Succeeded,
    Failed,
    Canceled,
    RolledBack,
    NeedsReboot,
}

/// Structured failure categories for the IPC error protocol.
///
/// Currently used only in the proto bridge layer (sysknife-types <-> sysknife-proto
/// conversions) and their tests. The daemon dispatcher uses string category
/// names on the wire today; these variants will replace those strings when the
/// daemon adopts the proto layer end-to-end.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FailureCategory {
    ValidationFailure,
    AuthorizationFailure,
    PolicyDenied,
    StaleApproval,
    ExecutionFailure,
    TransientInfrastructureFailure,
    Cancellation,
    StuckExecution,
    RebootRequired,
    RollbackFailure,
}

#[derive(Debug, thiserror::Error)]
pub enum BridgeError {
    #[error("invalid json payload for {0}")]
    InvalidJson(&'static str, #[source] serde_json::Error),

    #[error("invalid enum value {value} for {field}")]
    InvalidEnum { field: &'static str, value: i32 },
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct RequestEnvelope {
    pub action_name: String,
    pub request_id: String,
    pub params: Value,
    pub caller_role: CallerRole,
    pub request_hash: RequestHash,
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct PreviewEnvelope {
    pub summary: String,
    pub risk_level: RiskLevel,
    pub current_state: Value,
    pub proposed_change: Value,
    pub expected_side_effects: Vec<String>,
    pub reboot_required: bool,
    pub rollback_available: bool,
    pub warnings: Vec<String>,
    pub request_hash: RequestHash,
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ResultEnvelope {
    pub status: JobState,
    pub summary: String,
    pub warnings: Vec<String>,
    pub job_id: Option<String>,
    pub needs_reboot: bool,
    pub rollback_ref: Option<String>,
    pub transaction_id: String,
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct TransactionRecord {
    pub transaction_id: String,
    pub request_id: String,
    pub request_hash: String,
    pub action_name: String,
    pub risk_level: RiskLevel,
    pub status: JobState,
    pub approval_id: Option<String>,
    pub summary: String,
    pub warnings: Vec<String>,
}

impl From<CallerRole> for proto::CallerRole {
    // Matched directly against the variants rather than round-tripping through
    // an i32 code table, so a renumbered `.proto` moves this conversion along
    // with the prost-generated enum instead of drifting behind it. The
    // conversion is total, so it cannot panic.
    fn from(value: CallerRole) -> Self {
        match value {
            CallerRole::Observer => proto::CallerRole::Observer,
            CallerRole::Dev => proto::CallerRole::Dev,
            CallerRole::Admin => proto::CallerRole::Admin,
            CallerRole::Boot => proto::CallerRole::Boot,
        }
    }
}

impl TryFrom<proto::CallerRole> for CallerRole {
    type Error = BridgeError;

    fn try_from(value: proto::CallerRole) -> Result<Self, Self::Error> {
        match i32::from(value) {
            1 => Ok(CallerRole::Observer),
            2 => Ok(CallerRole::Dev),
            3 => Ok(CallerRole::Admin),
            4 => Ok(CallerRole::Boot),
            code => Err(BridgeError::InvalidEnum {
                field: "caller_role",
                value: code,
            }),
        }
    }
}

impl From<RiskLevel> for proto::RiskLevel {
    fn from(value: RiskLevel) -> Self {
        match value {
            RiskLevel::Low => proto::RiskLevel::Low,
            RiskLevel::Medium => proto::RiskLevel::Medium,
            RiskLevel::High => proto::RiskLevel::High,
        }
    }
}

impl TryFrom<proto::RiskLevel> for RiskLevel {
    type Error = BridgeError;

    fn try_from(value: proto::RiskLevel) -> Result<Self, Self::Error> {
        match i32::from(value) {
            1 => Ok(RiskLevel::Low),
            2 => Ok(RiskLevel::Medium),
            3 => Ok(RiskLevel::High),
            code => Err(BridgeError::InvalidEnum {
                field: "risk_level",
                value: code,
            }),
        }
    }
}

impl From<JobState> for proto::JobState {
    fn from(value: JobState) -> Self {
        match value {
            JobState::Queued => proto::JobState::Queued,
            JobState::Running => proto::JobState::Running,
            JobState::Succeeded => proto::JobState::Succeeded,
            JobState::Failed => proto::JobState::Failed,
            JobState::Canceled => proto::JobState::Canceled,
            JobState::RolledBack => proto::JobState::RolledBack,
            JobState::NeedsReboot => proto::JobState::NeedsReboot,
        }
    }
}

impl TryFrom<proto::JobState> for JobState {
    type Error = BridgeError;

    fn try_from(value: proto::JobState) -> Result<Self, Self::Error> {
        match i32::from(value) {
            1 => Ok(JobState::Queued),
            2 => Ok(JobState::Running),
            3 => Ok(JobState::Succeeded),
            4 => Ok(JobState::Failed),
            5 => Ok(JobState::Canceled),
            6 => Ok(JobState::RolledBack),
            7 => Ok(JobState::NeedsReboot),
            code => Err(BridgeError::InvalidEnum {
                field: "job_state",
                value: code,
            }),
        }
    }
}

impl From<FailureCategory> for proto::FailureCategory {
    fn from(value: FailureCategory) -> Self {
        match value {
            FailureCategory::ValidationFailure => proto::FailureCategory::ValidationFailure,
            FailureCategory::AuthorizationFailure => proto::FailureCategory::AuthorizationFailure,
            FailureCategory::PolicyDenied => proto::FailureCategory::PolicyDenied,
            FailureCategory::StaleApproval => proto::FailureCategory::StaleApproval,
            FailureCategory::ExecutionFailure => proto::FailureCategory::ExecutionFailure,
            FailureCategory::TransientInfrastructureFailure => {
                proto::FailureCategory::TransientInfrastructureFailure
            }
            FailureCategory::Cancellation => proto::FailureCategory::Cancellation,
            FailureCategory::StuckExecution => proto::FailureCategory::StuckExecution,
            FailureCategory::RebootRequired => proto::FailureCategory::RebootRequired,
            FailureCategory::RollbackFailure => proto::FailureCategory::RollbackFailure,
        }
    }
}

impl TryFrom<proto::FailureCategory> for FailureCategory {
    type Error = BridgeError;

    fn try_from(value: proto::FailureCategory) -> Result<Self, Self::Error> {
        match i32::from(value) {
            1 => Ok(FailureCategory::ValidationFailure),
            2 => Ok(FailureCategory::AuthorizationFailure),
            3 => Ok(FailureCategory::PolicyDenied),
            4 => Ok(FailureCategory::StaleApproval),
            5 => Ok(FailureCategory::ExecutionFailure),
            6 => Ok(FailureCategory::TransientInfrastructureFailure),
            7 => Ok(FailureCategory::Cancellation),
            8 => Ok(FailureCategory::StuckExecution),
            9 => Ok(FailureCategory::RebootRequired),
            10 => Ok(FailureCategory::RollbackFailure),
            code => Err(BridgeError::InvalidEnum {
                field: "failure_category",
                value: code,
            }),
        }
    }
}

impl From<RequestEnvelope> for proto::RequestEnvelope {
    fn from(value: RequestEnvelope) -> Self {
        Self {
            action_name: value.action_name,
            request_id: value.request_id,
            params_json: serde_json::to_string(&value.params).expect("json serialization"),
            caller_role: i32::from(proto::CallerRole::from(value.caller_role)),
            request_hash: value.request_hash.into_inner(),
        }
    }
}

impl TryFrom<proto::RequestEnvelope> for RequestEnvelope {
    type Error = BridgeError;

    fn try_from(value: proto::RequestEnvelope) -> Result<Self, Self::Error> {
        let params = serde_json::from_str(&value.params_json)
            .map_err(|error| BridgeError::InvalidJson("params_json", error))?;

        Ok(Self {
            action_name: value.action_name,
            request_id: value.request_id,
            params,
            caller_role: CallerRole::try_from(
                proto::CallerRole::try_from(value.caller_role).map_err(|_| {
                    BridgeError::InvalidEnum {
                        field: "caller_role",
                        value: value.caller_role,
                    }
                })?,
            )?,
            request_hash: RequestHash::from(value.request_hash),
        })
    }
}

impl From<PreviewEnvelope> for proto::PreviewEnvelope {
    fn from(value: PreviewEnvelope) -> Self {
        Self {
            summary: value.summary,
            risk_level: i32::from(proto::RiskLevel::from(value.risk_level)),
            current_state_json: serde_json::to_string(&value.current_state)
                .expect("json serialization"),
            proposed_change_json: serde_json::to_string(&value.proposed_change)
                .expect("json serialization"),
            expected_side_effects: value.expected_side_effects,
            reboot_required: value.reboot_required,
            rollback_available: value.rollback_available,
            warnings: value.warnings,
            request_hash: value.request_hash.into_inner(),
        }
    }
}

impl TryFrom<proto::PreviewEnvelope> for PreviewEnvelope {
    type Error = BridgeError;

    fn try_from(value: proto::PreviewEnvelope) -> Result<Self, Self::Error> {
        let current_state = serde_json::from_str(&value.current_state_json)
            .map_err(|error| BridgeError::InvalidJson("current_state_json", error))?;
        let proposed_change = serde_json::from_str(&value.proposed_change_json)
            .map_err(|error| BridgeError::InvalidJson("proposed_change_json", error))?;

        Ok(Self {
            summary: value.summary,
            risk_level: RiskLevel::try_from(
                proto::RiskLevel::try_from(value.risk_level).map_err(|_| {
                    BridgeError::InvalidEnum {
                        field: "risk_level",
                        value: value.risk_level,
                    }
                })?,
            )?,
            current_state,
            proposed_change,
            expected_side_effects: value.expected_side_effects,
            reboot_required: value.reboot_required,
            rollback_available: value.rollback_available,
            warnings: value.warnings,
            request_hash: RequestHash::from(value.request_hash),
        })
    }
}

impl From<ResultEnvelope> for proto::ResultEnvelope {
    fn from(value: ResultEnvelope) -> Self {
        Self {
            status: i32::from(proto::JobState::from(value.status)),
            summary: value.summary,
            warnings: value.warnings,
            job_id: value.job_id.unwrap_or_default(),
            needs_reboot: value.needs_reboot,
            rollback_ref: value.rollback_ref.unwrap_or_default(),
            transaction_id: value.transaction_id,
        }
    }
}

impl TryFrom<proto::ResultEnvelope> for ResultEnvelope {
    type Error = BridgeError;

    fn try_from(value: proto::ResultEnvelope) -> Result<Self, Self::Error> {
        Ok(Self {
            status: JobState::try_from(proto::JobState::try_from(value.status).map_err(|_| {
                BridgeError::InvalidEnum {
                    field: "job_state",
                    value: value.status,
                }
            })?)?,
            summary: value.summary,
            warnings: value.warnings,
            job_id: if value.job_id.is_empty() {
                None
            } else {
                Some(value.job_id)
            },
            needs_reboot: value.needs_reboot,
            rollback_ref: if value.rollback_ref.is_empty() {
                None
            } else {
                Some(value.rollback_ref)
            },
            transaction_id: value.transaction_id,
        })
    }
}

impl From<TransactionRecord> for proto::TransactionRecord {
    fn from(value: TransactionRecord) -> Self {
        Self {
            transaction_id: value.transaction_id,
            request_id: value.request_id,
            request_hash: value.request_hash,
            action_name: value.action_name,
            risk_level: i32::from(proto::RiskLevel::from(value.risk_level)),
            status: i32::from(proto::JobState::from(value.status)),
            approval_id: value.approval_id.unwrap_or_default(),
            summary: value.summary,
            warnings: value.warnings,
        }
    }
}

impl TryFrom<proto::TransactionRecord> for TransactionRecord {
    type Error = BridgeError;

    fn try_from(value: proto::TransactionRecord) -> Result<Self, Self::Error> {
        Ok(Self {
            transaction_id: value.transaction_id,
            request_id: value.request_id,
            request_hash: value.request_hash,
            action_name: value.action_name,
            risk_level: RiskLevel::try_from(
                proto::RiskLevel::try_from(value.risk_level).map_err(|_| {
                    BridgeError::InvalidEnum {
                        field: "risk_level",
                        value: value.risk_level,
                    }
                })?,
            )?,
            status: JobState::try_from(proto::JobState::try_from(value.status).map_err(|_| {
                BridgeError::InvalidEnum {
                    field: "job_state",
                    value: value.status,
                }
            })?)?,
            approval_id: if value.approval_id.is_empty() {
                None
            } else {
                Some(value.approval_id)
            },
            summary: value.summary,
            warnings: value.warnings,
        })
    }
}

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

    #[test]
    fn serde_round_trips_via_transparent_string() {
        // The newtype must serialise to a bare string so existing JSON IPC
        // frames continue to deserialise unchanged.
        let r = RequestHash::new("abc123".to_string());
        let json = serde_json::to_string(&r).unwrap();
        assert_eq!(json, "\"abc123\"");
        let back: RequestHash = serde_json::from_str("\"abc123\"").unwrap();
        assert_eq!(back, r);
    }
}

#[cfg(test)]
mod caller_role_ordering_tests {
    use super::CallerRole;

    #[test]
    fn caller_role_orders_least_to_most_privileged() {
        // The derived `Ord` IS the authorization comparison, so a variant
        // reordered during an edit would silently change who can do what.
        assert!(CallerRole::Observer < CallerRole::Dev);
        assert!(CallerRole::Dev < CallerRole::Admin);
        assert!(CallerRole::Admin < CallerRole::Boot);

        // The comparison call sites rely on this shape directly.
        assert!(CallerRole::Admin >= CallerRole::Dev);
        assert!(!(CallerRole::Observer >= CallerRole::Dev));
    }

    #[test]
    fn max_selects_the_higher_privilege() {
        // `highest_role_from_groups` folds with `max`; a user in both the
        // observer and admin groups must end up Admin.
        assert_eq!(
            CallerRole::Observer.max(CallerRole::Admin),
            CallerRole::Admin
        );
        assert_eq!(CallerRole::Boot.max(CallerRole::Dev), CallerRole::Boot);
    }
}

#[cfg(test)]
mod frame_limit_declaration_tests {
    use std::fs;
    use std::path::{Path, PathBuf};

    /// Walk the workspace root: climb from this crate's manifest dir until a
    /// `Cargo.toml` declaring `[workspace]` is found.
    fn workspace_root() -> PathBuf {
        let mut dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        loop {
            let manifest = dir.join("Cargo.toml");
            if manifest.is_file() {
                if let Ok(text) = fs::read_to_string(&manifest) {
                    if text.contains("[workspace]") {
                        return dir;
                    }
                }
            }
            if !dir.pop() {
                panic!("could not locate the workspace root");
            }
        }
    }

    /// Collect every `.rs` file under `dir`, skipping build output.
    fn walk_rs(dir: &Path, out: &mut Vec<PathBuf>) {
        if let Ok(entries) = fs::read_dir(dir) {
            for entry in entries.flatten() {
                let path = entry.path();
                if path.file_name().is_some_and(|n| n == "target") {
                    continue;
                }
                if path.is_dir() {
                    walk_rs(&path, out);
                } else if path.extension().is_some_and(|e| e == "rs") {
                    out.push(path);
                }
            }
        }
    }

    /// The 4 MiB frame limit must be declared in exactly one place.
    ///
    /// `MAX_MESSAGE_BYTES` is a wire fact and therefore lives only in
    /// `sysknife-types` (the protocol crate every side depends on). The daemon
    /// and CLI import it rather than redeclare it. If a second `4 MiB`
    /// *constant* is added anywhere in the daemon or CLI (a re-introduced
    /// `MAX_FRAME_BYTES`), the limit can silently diverge and one peer can
    /// reject frames the other side already accepted. That regression is what
    /// this test catches: it scans the workspace for constant *declarations*
    /// carrying the 4 MiB initialiser and requires exactly one, in this crate.
    ///
    /// Lines that merely use the literal as a buffer size (e.g. a
    /// `tokio::io::duplex(...)` in a test) or that reference the imported
    /// constant are not declarations and are intentionally ignored.
    ///
    /// The scan matches the `4 * 1024 * 1024` literal *form*, not the value:
    /// a re-declaration written as `4194304` or `4 << 20` would slip past it,
    /// as would one split across two lines. That is a known, accepted gap —
    /// the duplicates it must catch arrived as copy-pastes of the existing
    /// literal. No reader should over-trust it as a value-graph check.
    #[test]
    fn frame_limit_is_declared_once() {
        let root = workspace_root();
        let mut files: Vec<PathBuf> = Vec::new();
        for crate_dir in [
            "crates/sysknife-types",
            "crates/sysknife-daemon",
            "apps/sysknife-cli",
        ] {
            walk_rs(&root.join(crate_dir), &mut files);
        }

        let mut declarations: Vec<String> = Vec::new();
        for path in &files {
            let text = fs::read_to_string(path).unwrap();
            for (idx, raw) in text.lines().enumerate() {
                let line = raw.trim();
                let is_const_decl = [
                    "const ",
                    "pub const ",
                    "pub(crate) const ",
                    "pub(super) const ",
                ]
                .iter()
                .any(|p| line.starts_with(p));
                // A declaration names a constant AND carries the 4 MiB value.
                // Doc comments (start with `///`) and usages never both match.
                if is_const_decl && line.contains("4 * 1024 * 1024") {
                    declarations.push(format!("{}:{}", path.display(), idx + 1));
                }
            }
        }

        assert_eq!(
            declarations.len(),
            1,
            "expected exactly one declaration of the 4 MiB frame limit, \
             found {}:\n{:#?}",
            declarations.len(),
            declarations
        );
        let (decl_path, _line) = declarations[0].rsplit_once(':').unwrap();
        let relativized = PathBuf::from(decl_path.replace(&format!("{}/", root.display()), ""));
        assert_eq!(
            relativized,
            Path::new("crates/sysknife-types/src/lib.rs"),
            "the single frame-limit declaration must live in sysknife-types"
        );
    }
}