lix 0.18.0

use std::fmt::Write as _;

use serde_json::{Value as JsonValue, json};

/// Structured error type surfaced by Lix to every SDK binding.
///
/// Carries a machine-readable [`code`](Self::code), a human-readable
/// [`message`](Self::message), and an optional [`hint`](Self::hint)
/// suggesting how to recover. Hints follow the Postgres/rustc convention:
/// `message` states what went wrong in factual terms, and `hint` offers a
/// possible fix when one is known.
///
/// ```
/// use lix::LixError;
///
/// let err = LixError::new(
///     "LIX_ERROR_UNSUPPORTED_WRITE_EXPRESSION",
///     "json(...) is not supported",
/// )
/// .with_hint("cast the value with ::jsonb instead");
///
/// assert_eq!(err.hint(), Some("cast the value with ::jsonb instead"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LixError {
    pub code: String,
    pub message: String,
    pub hint: Option<String>,
    pub details: Option<Box<JsonValue>>,
}

impl LixError {
    /// True fallback — use when no more specific category fits. Producing
    /// sites should prefer the categorized codes below whenever possible;
    /// the SDK contract is that `LIX_ERROR_UNKNOWN` is the *last* resort,
    /// never the default.
    pub const CODE_UNKNOWN: &'static str = "LIX_ERROR_UNKNOWN";

    /// SQL text could not be parsed.
    pub const CODE_PARSE_ERROR: &'static str = "LIX_PARSE_ERROR";

    /// A SQL function name could not be resolved.
    pub const CODE_UDF_NOT_FOUND: &'static str = "LIX_UDF_NOT_FOUND";

    /// A SQL expression or function argument had an incompatible type.
    pub const CODE_TYPE_MISMATCH: &'static str = "LIX_TYPE_MISMATCH";

    /// A Lix JSON path argument used another dialect's path language instead
    /// of Lix's canonical variadic key/index segments.
    pub const CODE_INVALID_JSON_PATH: &'static str = "LIX_INVALID_JSON_PATH";

    /// SQL syntax belongs to another dialect and is outside the Lix SQL
    /// surface.
    pub const CODE_DIALECT_UNSUPPORTED: &'static str = "LIX_DIALECT_UNSUPPORTED";

    /// SQL parameters could not be bound to placeholders.
    pub const CODE_BINDING_ERROR: &'static str = "LIX_BINDING_ERROR";

    /// A caller supplied an invalid SQL parameter value or parameter list.
    pub const CODE_INVALID_PARAM: &'static str = "LIX_INVALID_PARAM";

    /// A SQL table or view name could not be resolved.
    pub const CODE_TABLE_NOT_FOUND: &'static str = "LIX_TABLE_NOT_FOUND";

    /// A SQL column name could not be resolved in the available projection.
    pub const CODE_COLUMN_NOT_FOUND: &'static str = "LIX_COLUMN_NOT_FOUND";

    /// A SQL write violated a primary-key, unique, NOT NULL, or other
    /// relational constraint.
    pub const CODE_CONSTRAINT_VIOLATION: &'static str = "LIX_CONSTRAINT_VIOLATION";

    /// A SQL write targeted a read-only internal/component surface.
    pub const CODE_READ_ONLY: &'static str = "LIX_ERROR_READ_ONLY";

    /// A partial replica cannot prove completeness for a global history surface.
    /// Single read statements may be retried against the configured authority.
    pub const CODE_PARTIAL_REPLICA_SCOPE_UNSUPPORTED: &'static str =
        "LIX_PARTIAL_REPLICA_SCOPE_UNSUPPORTED";

    /// SQL syntax is valid, but the feature is intentionally outside the Lix
    /// SQL surface.
    pub const CODE_UNSUPPORTED_SQL: &'static str = "LIX_UNSUPPORTED_SQL";

    /// SQL planning succeeded far enough to produce a physical runtime shape
    /// that the current engine target cannot execute safely.
    pub const CODE_UNSUPPORTED_SQL_RUNTIME_PLAN: &'static str = "LIX_UNSUPPORTED_SQL_RUNTIME_PLAN";

    /// Another owner already has exclusive access to this storage.
    pub const CODE_STORAGE_IN_USE: &'static str = "LIX_STORAGE_IN_USE";

    /// A storage operation failed.
    pub const CODE_STORAGE_ERROR: &'static str = "LIX_STORAGE_ERROR";

    /// The storage service could not complete an I/O operation. A connected
    /// replica may retry its idempotent sync request after the backend recovers.
    pub const CODE_STORAGE_IO_UNAVAILABLE: &'static str = "LIX_STORAGE_IO_UNAVAILABLE";

    /// Stored data failed an integrity check. Retrying the same sync request
    /// cannot repair the repository and must not hide the failure.
    pub const CODE_STORAGE_CORRUPTION: &'static str = "LIX_STORAGE_CORRUPTION";

    /// A coherent storage read was invalidated by a concurrent commit.
    /// Auto-commit read surfaces consume this internally by reopening the
    /// complete read/query against a fresh snapshot.
    pub const CODE_STORAGE_READ_EXPIRED: &'static str = "LIX_STORAGE_READ_EXPIRED";

    /// The selected storage cannot prove the requested persistence boundary.
    pub const CODE_STORAGE_DURABILITY_UNAVAILABLE: &'static str =
        "LIX_STORAGE_DURABILITY_UNAVAILABLE";

    /// A snapshot is malformed, unsupported, truncated, or fails integrity
    /// verification.
    pub const CODE_INVALID_SNAPSHOT: &'static str = "LIX_INVALID_SNAPSHOT";

    /// Reading or writing a snapshot stream failed.
    pub const CODE_SNAPSHOT_IO: &'static str = "LIX_SNAPSHOT_IO";

    /// A newer storage client fenced this writer, so this Lix instance can no
    /// longer serve requests.
    pub const CODE_STORAGE_FENCED: &'static str = "LIX_STORAGE_FENCED";

    /// The backing storage instance stopped and this Lix instance can no
    /// longer serve requests.
    pub const CODE_STORAGE_CLOSED: &'static str = "LIX_STORAGE_CLOSED";

    /// A storage commit may have been applied, but its caller did not receive
    /// a definitive result.
    pub const CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN: &'static str =
        "LIX_STORAGE_COMMIT_OUTCOME_UNKNOWN";

    /// A server SQL mutation did not provide the required replay identity.
    pub const CODE_IDEMPOTENCY_KEY_REQUIRED: &'static str = "LIX_IDEMPOTENCY_KEY_REQUIRED";

    /// A replay identity was reused for a different logical mutation.
    pub const CODE_IDEMPOTENCY_KEY_REUSED: &'static str = "LIX_IDEMPOTENCY_KEY_REUSED";

    /// A mutation response cannot be retained safely for idempotent replay.
    pub const CODE_IDEMPOTENCY_RESPONSE_TOO_LARGE: &'static str =
        "LIX_IDEMPOTENCY_RESPONSE_TOO_LARGE";

    /// Optimistic transaction publication lost a race with a newer commit.
    pub const CODE_TRANSACTION_CONFLICT: &'static str = "LIX_TRANSACTION_CONFLICT";

    /// An internal engine invariant failed.
    pub const CODE_INTERNAL_ERROR: &'static str = "LIX_INTERNAL_ERROR";

    /// A plugin ZIP package or manifest is malformed, unsafe, or exceeds the
    /// static resource bounds accepted by the engine. Invalid embedded Lix
    /// schema definitions retain [`Self::CODE_SCHEMA_DEFINITION`].
    pub const CODE_INVALID_PLUGIN: &'static str = "LIX_ERROR_INVALID_PLUGIN";

    /// A file is materialized as durable plugin state, but the plugin needed
    /// to render that state is not installed on the file's branch.
    pub const CODE_PLUGIN_UNAVAILABLE: &'static str = "LIX_ERROR_PLUGIN_UNAVAILABLE";

    /// An incremental plugin write did not carry an exact, still-current
    /// private document observation. The client must re-read the file; the
    /// engine never guesses identity authority from equal byte hashes.
    pub const CODE_PLUGIN_OBSERVATION_STALE: &'static str = "LIX_ERROR_PLUGIN_OBSERVATION_STALE";

    /// Creating another live plugin Store would exceed the repository-wide
    /// runtime admission limit configured for this Engine.
    pub const CODE_PLUGIN_RESOURCE_LIMIT: &'static str = "LIX_ERROR_PLUGIN_RESOURCE_LIMIT";

    /// Write-time failure where user data did not conform to a registered
    /// schema (type mismatch, missing required field, pattern violation,
    /// additionalProperties, etc.). Raised from the JSON-Schema validator
    /// run over a candidate row's snapshot.
    pub const CODE_SCHEMA_VALIDATION: &'static str = "LIX_ERROR_SCHEMA_VALIDATION";

    /// A foreign-key constraint could not be satisfied. Covers both the
    /// insert-side "no matching target row" failure and the delete-side
    /// "still referenced" (restrict) failure.
    pub const CODE_FOREIGN_KEY: &'static str = "LIX_ERROR_FOREIGN_KEY";

    /// A row references a non-null `file_id` that has no matching `lix_file`
    /// descriptor in the same effective branch scope.
    pub const CODE_FILE_NOT_FOUND: &'static str = "LIX_ERROR_FILE_NOT_FOUND";

    /// A primary-key or `x-lix-unique` constraint was violated — another
    /// row already owns the value(s) for the declared pointer group.
    pub const CODE_UNIQUE: &'static str = "LIX_ERROR_UNIQUE";

    /// An `INSERT ... VALUES (...)` expression is not supported by the
    /// public write surface (e.g. `json(...)`, subqueries, arbitrary SQL
    /// expressions). Users should cast inline JSON with `::jsonb`.
    pub const CODE_UNSUPPORTED_WRITE_EXPRESSION: &'static str =
        "LIX_ERROR_UNSUPPORTED_WRITE_EXPRESSION";

    /// The schema JSON itself (the *definition*, not a row against it) is
    /// malformed — a missing `key`, an invalid primary-key column, or another
    /// leading slash, a reserved-namespace collision, or any other
    /// meta-schema validation failure.
    pub const CODE_SCHEMA_DEFINITION: &'static str = "LIX_ERROR_SCHEMA_DEFINITION";

    /// A public runtime schema registration attempted to use the `lix_*`
    /// namespace reserved for schemas owned and bootstrapped by Lix.
    pub const CODE_RESERVED_SCHEMA_NAMESPACE: &'static str = "LIX_RESERVED_SCHEMA_NAMESPACE";

    /// The logical Lix handle/session has been closed and cannot run further
    /// operations. Close is a resource-release lifecycle boundary, not a
    /// durability boundary.
    pub const CODE_CLOSED: &'static str = "LIX_ERROR_CLOSED";

    /// An operation is incompatible with the current session mode or state.
    pub const CODE_INVALID_SESSION_STATE: &'static str = "LIX_INVALID_SESSION_STATE";

    /// A mutation is incompatible with the current explicit transaction state.
    pub const CODE_INVALID_TRANSACTION_STATE: &'static str = "LIX_INVALID_TRANSACTION_STATE";

    /// Plugin ownership or generations are incompatible, or a tracked change
    /// collides with an untracked row. Ordinary overlapping row edits reconcile
    /// automatically.
    pub const CODE_MERGE_CONFLICT: &'static str = "LIX_MERGE_CONFLICT";

    /// A caller referenced a branch id that has no matching branch ref.
    pub const CODE_BRANCH_NOT_FOUND: &'static str = "LIX_BRANCH_NOT_FOUND";

    /// A caller referenced a commit id that has no matching commit record.
    pub const CODE_COMMIT_NOT_FOUND: &'static str = "LIX_COMMIT_NOT_FOUND";

    /// A staged row's storage scope flags disagree, such as a global row not
    /// using the reserved global branch id.
    pub const CODE_INVALID_STORAGE_SCOPE: &'static str = "LIX_ERROR_INVALID_STORAGE_SCOPE";

    /// Merge graph analysis found multiple equally valid merge bases.
    pub const CODE_AMBIGUOUS_MERGE_BASE: &'static str = "LIX_AMBIGUOUS_MERGE_BASE";

    /// A merge request is well-formed but nonsensical for the commit graph,
    /// such as merging a branch into itself.
    pub const CODE_INVALID_MERGE: &'static str = "LIX_INVALID_MERGE";

    /// The selected branch has no ordinary commit above its undo boundary.
    pub const CODE_NOTHING_TO_UNDO: &'static str = "LIX_NOTHING_TO_UNDO";

    /// The selected branch has no abandoned action available to replay.
    pub const CODE_NOTHING_TO_REDO: &'static str = "LIX_NOTHING_TO_REDO";

    /// An operation may have completed even when its completion work failed.
    /// Retry classification must check this before considering a transient code.
    /// Reading an idempotency receipt remains safe; executing the operation again does not.
    pub(crate) fn automatic_retry_is_forbidden(&self) -> bool {
        self.code == Self::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN
            || ["nonRetryableAfterCommit", "nonRetryableAfterExecution"]
                .iter()
                .any(|key| {
                    self.details
                        .as_ref()
                        .and_then(|details| details.get(key))
                        .and_then(JsonValue::as_bool)
                        == Some(true)
                })
    }

    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            code: code.into(),
            message: message.into(),
            hint: None,
            details: None,
        }
    }

    pub fn unknown(message: impl Into<String>) -> Self {
        Self::new("LIX_ERROR_UNKNOWN", message)
    }

    pub fn branch_not_found(
        branch_id: impl Into<String>,
        operation: impl Into<String>,
        role: impl Into<String>,
    ) -> Self {
        let branch_id = branch_id.into();
        let operation = operation.into();
        let role = role.into();
        Self::new(
            Self::CODE_BRANCH_NOT_FOUND,
            format!("branch '{branch_id}' was not found"),
        )
        .with_details(json!({
            "branch_id": branch_id,
            "operation": operation,
            "role": role,
        }))
    }

    pub fn commit_not_found(
        commit_id: impl Into<String>,
        operation: impl Into<String>,
        role: impl Into<String>,
    ) -> Self {
        let commit_id = commit_id.into();
        let operation = operation.into();
        let role = role.into();
        Self::new(
            Self::CODE_COMMIT_NOT_FOUND,
            format!("commit '{commit_id}' was not found"),
        )
        .with_details(json!({
            "commit_id": commit_id,
            "operation": operation,
            "role": role,
        }))
    }

    /// A row could not be normalized because its schema is outside the
    /// transaction's visible commit graph and durability scope.
    pub fn schema_not_visible(
        schema_key: impl Into<String>,
        entity_commit_id: Option<impl Into<String>>,
        base_commit_id: Option<impl Into<String>>,
        branch_id: impl Into<String>,
        untracked: bool,
    ) -> Self {
        let schema_key = schema_key.into();
        let entity_commit_id = entity_commit_id.map(Into::into);
        let base_commit_id = base_commit_id.map(Into::into);
        let branch_id = branch_id.into();
        let scope = format!("branch:{branch_id}");
        let hint = match (entity_commit_id.as_deref(), base_commit_id.as_deref()) {
            (Some(entity_commit_id), Some(base_commit_id))
                if entity_commit_id != base_commit_id =>
            {
                format!(
                    "The entity comes from commit {entity_commit_id}, but schema '{schema_key}' is not visible from this transaction's base commit {base_commit_id} in {scope} ({} lane). This usually indicates that the entity commit is not an ancestor of the transaction base, or that the schema was registered in a different branch or durability scope.",
                    if untracked { "untracked" } else { "tracked" }
                )
            }
            (_, Some(base_commit_id)) => format!(
                "Schema '{schema_key}' is not visible from this transaction's base commit {base_commit_id} in {scope} ({} lane). This usually indicates that the schema was registered in a different branch or durability scope.",
                if untracked { "untracked" } else { "tracked" }
            ),
            _ => format!(
                "Schema '{schema_key}' is not visible in {scope} ({} lane). This usually indicates that the schema was registered in a different branch or durability scope.",
                if untracked { "untracked" } else { "tracked" }
            ),
        };
        let mut details = serde_json::Map::from_iter([
            (
                "schema_key".to_string(),
                JsonValue::String(schema_key.clone()),
            ),
            ("scope".to_string(), JsonValue::String(scope)),
            (
                "durability".to_string(),
                JsonValue::String(if untracked { "untracked" } else { "tracked" }.to_string()),
            ),
        ]);
        if let Some(entity_commit_id) = entity_commit_id {
            details.insert(
                "entity_commit_id".to_string(),
                JsonValue::String(entity_commit_id),
            );
        }
        if let Some(base_commit_id) = base_commit_id {
            details.insert(
                "base_commit_id".to_string(),
                JsonValue::String(base_commit_id),
            );
        }
        Self::new(
            Self::CODE_SCHEMA_DEFINITION,
            format!("schema '{schema_key}' is not visible to this transaction"),
        )
        .with_details(JsonValue::Object(details))
        .with_hint(hint)
    }

    /// Construct an internal invariant failure with the entity coordinates
    /// needed to turn the surfaced error into an actionable bug report.
    pub fn internal_invariant(message: impl Into<String>, entities: JsonValue) -> Self {
        Self::new(Self::CODE_INTERNAL_ERROR, message).with_details(entities)
    }

    pub fn ambiguous_merge_base(
        left_commit_id: impl Into<String>,
        right_commit_id: impl Into<String>,
        candidates: Vec<String>,
    ) -> Self {
        let left_commit_id = left_commit_id.into();
        let right_commit_id = right_commit_id.into();
        Self::new(
            Self::CODE_AMBIGUOUS_MERGE_BASE,
            format!("ambiguous merge base between '{left_commit_id}' and '{right_commit_id}'"),
        )
        .with_details(json!({
            "left_commit_id": left_commit_id,
            "right_commit_id": right_commit_id,
            "candidates": candidates,
        }))
    }

    pub fn invalid_self_merge(branch_id: impl Into<String>) -> Self {
        let branch_id = branch_id.into();
        Self::new(
            Self::CODE_INVALID_MERGE,
            format!("cannot merge branch '{branch_id}' into itself"),
        )
        .with_details(json!({
            "operation": "merge_branch",
            "target_branch_id": branch_id,
            "source_branch_id": branch_id,
        }))
    }

    /// Attach a hint to this error. Consumers render hints alongside the
    /// primary message (e.g. a CLI prints them as `hint: <text>`).
    ///
    /// ```
    /// use lix::LixError;
    ///
    /// let err = LixError::new("CODE", "boom").with_hint("try this");
    /// assert_eq!(err.hint(), Some("try this"));
    /// ```
    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
        self.hint = Some(hint.into());
        self
    }

    /// Attach machine-readable details to this error.
    pub fn with_details(mut self, details: JsonValue) -> Self {
        self.details = Some(Box::new(details));
        self
    }

    /// Return the attached hint, if any.
    ///
    /// Returns `None` when no hint was attached at the error's producer
    /// site. This is the accessor SDK consumers should prefer over
    /// reading the `hint` field directly — it returns `Option<&str>`,
    /// avoiding the need for `.as_deref()` at the call site.
    ///
    /// ```
    /// use lix::LixError;
    ///
    /// let without_hint = LixError::new("CODE", "boom");
    /// assert_eq!(without_hint.hint(), None);
    ///
    /// let with_hint = LixError::new("CODE", "boom").with_hint("fix it");
    /// assert_eq!(with_hint.hint(), Some("fix it"));
    /// ```
    pub fn hint(&self) -> Option<&str> {
        self.hint.as_deref()
    }

    /// Return the attached structured details, if any.
    pub fn details(&self) -> Option<&JsonValue> {
        self.details.as_deref()
    }

    /// Return the attached structured details mutably, if any.
    pub fn details_mut(&mut self) -> Option<&mut JsonValue> {
        self.details.as_deref_mut()
    }

    pub fn format(&self) -> String {
        let mut s = format!("code: {}\nmessage: {}", self.code, self.message);
        if let Some(hint) = &self.hint {
            let _ = write!(s, "\nhint: {hint}");
        }
        s
    }
}

impl From<crate::storage_adapter::StorageError> for LixError {
    fn from(error: crate::storage_adapter::StorageError) -> Self {
        match error {
            crate::storage_adapter::StorageError::InUse => Self::new(
                Self::CODE_STORAGE_IN_USE,
                "storage is already open by another owner",
            )
            .with_hint("Use the existing repository owner, or close it before reopening."),
            crate::storage_adapter::StorageError::WriteConflict
            | crate::storage_adapter::StorageError::PreconditionFailed(_) => Self::new(
                Self::CODE_TRANSACTION_CONFLICT,
                "transaction snapshot is stale because tracked state changed before commit",
            )
            .with_hint("Retry the transaction against the latest committed state.")
            .with_details(json!({
                "retryable": true,
                "reason": "commitRaced",
            })),
            crate::storage_adapter::StorageError::Fenced => Self::new(
                Self::CODE_STORAGE_FENCED,
                "the storage writer was fenced by a newer client",
            )
            .with_hint(
                "Do not automatically retry this request; a mutation may still have completed.",
            )
            .with_details(json!({
                "retryable": false,
                "outcome": "unknown",
            })),
            crate::storage_adapter::StorageError::Closed(_) => Self::new(
                Self::CODE_STORAGE_CLOSED,
                "the storage instance closed and must be reopened",
            )
            .with_hint(
                "Do not automatically retry this request; a mutation may still have completed.",
            )
            .with_details(json!({
                "retryable": false,
                "outcome": "unknown",
            })),
            crate::storage_adapter::StorageError::CommitOutcomeUnknown(message) => Self::new(
                Self::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN,
                format!("the storage commit outcome is unknown: {message}"),
            )
            .with_hint(
                "Do not automatically retry this request; a mutation may still have completed.",
            )
            .with_details(json!({
                "retryable": false,
                "outcome": "unknown",
            })),
            crate::storage_adapter::StorageError::Durability => Self::new(
                Self::CODE_STORAGE_DURABILITY_UNAVAILABLE,
                "the storage backend cannot prove the requested durability boundary",
            ),
            crate::storage_adapter::StorageError::ReadExpired => Self::new(
                Self::CODE_STORAGE_READ_EXPIRED,
                "the coherent storage read was invalidated by a concurrent commit",
            )
            .with_details(json!({
                "retryable": true,
            })),
            crate::storage_adapter::StorageError::Unavailable(message) => Self::new(
                Self::CODE_STORAGE_IO_UNAVAILABLE,
                format!("storage unavailable: {message}"),
            ),
            crate::storage_adapter::StorageError::Corruption(message) => Self::new(
                Self::CODE_STORAGE_CORRUPTION,
                format!("storage corruption: {message}"),
            ),
            error => Self::new(Self::CODE_STORAGE_ERROR, error.to_string()),
        }
    }
}

impl From<crate::storage_adapter::StorageWriteSetError> for LixError {
    fn from(error: crate::storage_adapter::StorageWriteSetError) -> Self {
        match error {
            crate::storage_adapter::StorageWriteSetError::Storage(error) => error.into(),
            error => Self::new(Self::CODE_STORAGE_ERROR, error.to_string()),
        }
    }
}

impl std::fmt::Display for LixError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.format())
    }
}

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

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

    #[test]
    fn automatic_retry_respects_completion_markers_before_error_category() {
        for code in [
            LixError::CODE_TRANSACTION_CONFLICT,
            LixError::CODE_STORAGE_READ_EXPIRED,
            LixError::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN,
            "typed-native-demand",
        ] {
            let error = LixError::new(code, "original diagnostic");
            assert_eq!(
                error.automatic_retry_is_forbidden(),
                code == LixError::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN
            );
            for marker in ["nonRetryableAfterCommit", "nonRetryableAfterExecution"] {
                for value in [json!(true), json!(false), json!(null), json!("true")] {
                    let marked = error.clone().with_details(json!({marker: value}));
                    assert_eq!(
                        marked.automatic_retry_is_forbidden(),
                        value == json!(true)
                            || code == LixError::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN
                    );
                }
            }
        }
    }

    #[test]
    fn format_without_hint_omits_hint_line() {
        let err = LixError::new("LIX_ERROR_FOO", "something went wrong");
        assert_eq!(
            err.format(),
            "code: LIX_ERROR_FOO\nmessage: something went wrong"
        );
        assert!(err.hint.is_none());
    }

    #[test]
    fn format_with_hint_appends_hint_line() {
        let err = LixError::new("LIX_ERROR_FOO", "something went wrong").with_hint("try the fix");
        assert_eq!(
            err.format(),
            "code: LIX_ERROR_FOO\nmessage: something went wrong\nhint: try the fix"
        );
    }

    #[test]
    fn with_hint_is_chainable_and_replaces_prior_hint() {
        let err = LixError::new("LIX_ERROR_FOO", "desc")
            .with_hint("first")
            .with_hint("second");
        assert_eq!(err.hint.as_deref(), Some("second"));
    }

    #[test]
    fn new_defaults_hint_to_none() {
        let err = LixError::new("CODE", "desc");
        assert_eq!(err.hint, None);
    }

    #[test]
    fn unknown_defaults_hint_to_none() {
        let err = LixError::unknown("desc");
        assert_eq!(err.code, "LIX_ERROR_UNKNOWN");
        assert_eq!(err.hint, None);
    }

    #[test]
    fn fenced_storage_error_is_terminal_and_not_retryable() {
        let error = LixError::from(crate::storage::StorageError::Fenced);

        assert_eq!(error.code, LixError::CODE_STORAGE_FENCED);
        assert_eq!(
            error.details(),
            Some(&serde_json::json!({
                "retryable": false,
                "outcome": "unknown",
            }))
        );
    }

    #[test]
    fn unknown_commit_outcome_is_not_retryable() {
        let error = LixError::from(crate::storage::StorageError::CommitOutcomeUnknown(
            "storage reply was lost after commit".to_string(),
        ));

        assert_eq!(error.code, LixError::CODE_STORAGE_COMMIT_OUTCOME_UNKNOWN);
        assert_eq!(
            error.details(),
            Some(&serde_json::json!({
                "retryable": false,
                "outcome": "unknown",
            }))
        );
        assert_eq!(
            error.hint(),
            Some("Do not automatically retry this request; a mutation may still have completed.")
        );
    }

    #[test]
    fn fenced_storage_write_set_error_preserves_the_terminal_code() {
        let error = LixError::from(crate::storage_adapter::StorageWriteSetError::Storage(
            crate::storage::StorageError::Fenced,
        ));

        assert_eq!(error.code, LixError::CODE_STORAGE_FENCED);
    }

    #[test]
    fn closed_storage_error_is_terminal_and_not_retryable() {
        let error = LixError::from(crate::storage::StorageError::Closed(
            "background worker panicked".to_string(),
        ));

        assert_eq!(error.code, LixError::CODE_STORAGE_CLOSED);
        assert_eq!(
            error.details(),
            Some(&serde_json::json!({
                "retryable": false,
                "outcome": "unknown",
            }))
        );
    }

    #[test]
    fn storage_io_and_corruption_keep_distinct_sync_error_codes() {
        let io = LixError::from(crate::storage::StorageError::Unavailable(
            "object store PUT failed".to_string(),
        ));
        assert_eq!(io.code, LixError::CODE_STORAGE_IO_UNAVAILABLE);
        assert!(!io.automatic_retry_is_forbidden());

        let deterministic_io = LixError::from(crate::storage::StorageError::Io(
            "read discovery byte limit exceeded".to_string(),
        ));
        assert_eq!(deterministic_io.code, LixError::CODE_STORAGE_ERROR);

        let corruption = LixError::from(crate::storage::StorageError::Corruption(
            "segment hash mismatch".to_string(),
        ));
        assert_eq!(corruption.code, LixError::CODE_STORAGE_CORRUPTION);
    }
}