crtx-store 0.1.1

//! Contradiction repository operations.
//!
//! ADR 0024 makes contradictions a first-class durable surface, and ADR 0026
//! §2 requires every mutation of that surface to compose through the policy
//! lattice. Every state-changing entry point on [`ContradictionRepo`] now
//! requires the caller to pass a composed [`PolicyDecision`] whose contributing
//! rules name the ADR 0024 invariants being asserted.
//!
//! Required contributor rule ids:
//!
//! - [`INSERT_SCOPE_VALIDITY_RULE_ID`] and [`INSERT_UNRESOLVED_STATE_RULE_ID`]
//!   for [`ContradictionRepo::insert`].
//! - [`TRANSITION_ACTOR_AUTHORITY_RULE_ID`] and
//!   [`TRANSITION_RESOLUTION_EVIDENCE_RULE_ID`] for every transition
//!   ([`ContradictionRepo::interpret`], [`ContradictionRepo::resolve`],
//!   [`ContradictionRepo::delete`]).
//! - [`TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID`] additionally on
//!   [`ContradictionRepo::resolve`] and [`ContradictionRepo::delete`] — these
//!   close the ADR 0024 slot and ADR 0023 §3 requires the operator carrying the
//!   resolution to currently hold the authority.

use chrono::{DateTime, Utc};
use cortex_core::{
    ContradictionId, PolicyContribution, PolicyDecision, PolicyOutcome, TemporalAuthorityReport,
};
use rusqlite::{params, OptionalExtension, Row};

use crate::{Pool, StoreError, StoreResult};

macro_rules! contradiction_select_sql {
    ($where_clause:literal) => {
        concat!(
            "SELECT id, left_ref, right_ref, contradiction_type, status, interpretation,
                    created_at, updated_at
             FROM contradictions ",
            $where_clause,
            ";"
        )
    };
}

/// Required contributor rule id documenting that the contradiction scope
/// (left/right refs + contradiction kind) was validated by the caller before
/// the row was persisted (ADR 0024 §3 `claim_key` framing, ADR 0026 §5).
pub const INSERT_SCOPE_VALIDITY_RULE_ID: &str = "contradictions.insert.scope_validity";
/// Required contributor rule id documenting that the caller asserted the
/// initial lifecycle state for a newly inserted contradiction (ADR 0024 §3
/// `ConflictUnresolved`, ADR 0026 §5).
pub const INSERT_UNRESOLVED_STATE_RULE_ID: &str = "contradictions.insert.unresolved_state";
/// Required contributor rule id documenting the actor authority backing a
/// contradiction lifecycle transition (ADR 0024 §4 operator path, ADR 0026 §4).
pub const TRANSITION_ACTOR_AUTHORITY_RULE_ID: &str = "contradictions.transition.actor_authority";
/// Required contributor rule id documenting the evidence backing a resolution
/// or interpretation note (ADR 0024 §4 `audit_records`, ADR 0026 §7).
pub const TRANSITION_RESOLUTION_EVIDENCE_RULE_ID: &str =
    "contradictions.transition.resolution_evidence";
/// Required contributor rule id documenting that the operator carrying a
/// closing transition (`resolve` / `delete`) currently holds the required
/// temporal authority (ADR 0023 §3 current-use, ADR 0026 §4).
pub const TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID: &str =
    "contradictions.transition.operator_temporal_authority";

/// Durable contradiction status.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ContradictionStatus {
    /// Detected, not yet interpreted.
    Unresolved,
    /// Interpreted, but still open.
    Interpreted,
    /// Closed by an explicit resolution.
    Resolved,
}

impl ContradictionStatus {
    /// Returns the stable SQLite wire value.
    #[must_use]
    pub const fn wire(self) -> &'static str {
        match self {
            Self::Unresolved => "unresolved",
            Self::Interpreted => "interpreted",
            Self::Resolved => "resolved",
        }
    }

    /// Whether this status still represents an open conflict.
    #[must_use]
    pub const fn is_open(self) -> bool {
        matches!(self, Self::Unresolved | Self::Interpreted)
    }
}

/// Durable contradiction row matching the current store schema.
#[derive(Debug, Clone, PartialEq)]
pub struct ContradictionRecord {
    /// Stable contradiction identifier.
    pub id: ContradictionId,
    /// Left memory/principle/reference.
    pub left_ref: String,
    /// Right memory/principle/reference.
    pub right_ref: String,
    /// Conflict kind.
    pub contradiction_type: String,
    /// Current lifecycle status.
    pub status: ContradictionStatus,
    /// Interpretation or resolution note.
    pub interpretation: Option<String>,
    /// Creation timestamp.
    pub created_at: DateTime<Utc>,
    /// Last update timestamp.
    pub updated_at: DateTime<Utc>,
}

/// Repository for first-class contradiction rows.
#[derive(Debug)]
pub struct ContradictionRepo<'a> {
    pool: &'a Pool,
}

impl<'a> ContradictionRepo<'a> {
    /// Creates a contradiction repository over an open SQLite connection.
    #[must_use]
    pub const fn new(pool: &'a Pool) -> Self {
        Self { pool }
    }

    /// Inserts one unresolved/interpreted/resolved contradiction row through
    /// the ADR 0026 enforcement lattice.
    ///
    /// `policy` is the composed [`PolicyDecision`] for this insertion and MUST
    /// satisfy:
    ///
    /// 1. The final outcome is one of [`PolicyOutcome::Allow`],
    ///    [`PolicyOutcome::Warn`], or [`PolicyOutcome::BreakGlass`]. A
    ///    `Quarantine` or `Reject` decision fails closed and writes nothing.
    /// 2. The composition includes contributors for both
    ///    [`INSERT_SCOPE_VALIDITY_RULE_ID`] and
    ///    [`INSERT_UNRESOLVED_STATE_RULE_ID`]. The repo refuses callers that
    ///    skipped composition.
    pub fn insert(
        &self,
        contradiction: &ContradictionRecord,
        policy: &PolicyDecision,
    ) -> StoreResult<()> {
        require_policy_final_outcome(policy, "contradictions.insert")?;
        require_contributor_rule(policy, INSERT_SCOPE_VALIDITY_RULE_ID)?;
        require_contributor_rule(policy, INSERT_UNRESOLVED_STATE_RULE_ID)?;

        validate_record(contradiction)?;
        self.pool.execute(
            "INSERT INTO contradictions (
                id, left_ref, right_ref, contradiction_type, status, interpretation,
                created_at, updated_at
             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8);",
            params![
                contradiction.id.to_string(),
                contradiction.left_ref,
                contradiction.right_ref,
                contradiction.contradiction_type,
                contradiction.status.wire(),
                contradiction.interpretation,
                contradiction.created_at.to_rfc3339(),
                contradiction.updated_at.to_rfc3339(),
            ],
        )?;

        Ok(())
    }

    /// Fetches a contradiction by id.
    pub fn get_by_id(&self, id: &ContradictionId) -> StoreResult<Option<ContradictionRecord>> {
        let row = self
            .pool
            .query_row(
                contradiction_select_sql!("WHERE id = ?1"),
                params![id.to_string()],
                contradiction_row,
            )
            .optional()?;

        row.map(TryInto::try_into).transpose()
    }

    /// Lists all contradiction rows in deterministic creation order.
    pub fn list(&self) -> StoreResult<Vec<ContradictionRecord>> {
        let mut stmt = self
            .pool
            .prepare(contradiction_select_sql!("ORDER BY created_at, id"))?;
        let rows = stmt.query_map([], contradiction_row)?;
        collect_records(rows)
    }

    /// Lists contradictions with the requested status.
    pub fn list_by_status(
        &self,
        status: ContradictionStatus,
    ) -> StoreResult<Vec<ContradictionRecord>> {
        let mut stmt = self.pool.prepare(contradiction_select_sql!(
            "WHERE status = ?1 ORDER BY created_at, id"
        ))?;
        let rows = stmt.query_map(params![status.wire()], contradiction_row)?;
        collect_records(rows)
    }

    /// Lists unresolved and interpreted contradictions.
    pub fn list_open(&self) -> StoreResult<Vec<ContradictionRecord>> {
        let mut stmt = self.pool.prepare(contradiction_select_sql!(
            "WHERE status IN ('unresolved', 'interpreted') ORDER BY created_at, id"
        ))?;
        let rows = stmt.query_map([], contradiction_row)?;
        collect_records(rows)
    }

    /// Marks a contradiction interpreted but still open through the ADR 0026
    /// enforcement lattice.
    ///
    /// `policy` must compose [`TRANSITION_ACTOR_AUTHORITY_RULE_ID`] and
    /// [`TRANSITION_RESOLUTION_EVIDENCE_RULE_ID`] contributors. Interpretation
    /// leaves the slot open per ADR 0024 §3 so it does NOT require a temporal
    /// authority contributor — that gate fires only on closing transitions.
    pub fn interpret(
        &self,
        id: &ContradictionId,
        interpretation: &str,
        updated_at: DateTime<Utc>,
        policy: &PolicyDecision,
    ) -> StoreResult<()> {
        require_transition_policy(policy, "contradictions.interpret", false)?;
        update_status(
            self.pool,
            id,
            ContradictionStatus::Interpreted,
            interpretation,
            updated_at,
        )
    }

    /// Marks a contradiction resolved through the ADR 0026 enforcement lattice.
    ///
    /// `policy` must compose
    /// [`TRANSITION_ACTOR_AUTHORITY_RULE_ID`],
    /// [`TRANSITION_RESOLUTION_EVIDENCE_RULE_ID`], and
    /// [`TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID`] contributors.
    /// Resolution closes the ADR 0024 `claim_key` slot, and ADR 0023 §3
    /// requires the operator carrying the close to currently hold the
    /// authority. See [`contradiction_resolve_policy_from_temporal_report`].
    pub fn resolve(
        &self,
        id: &ContradictionId,
        resolution: &str,
        updated_at: DateTime<Utc>,
        policy: &PolicyDecision,
    ) -> StoreResult<()> {
        require_transition_policy(policy, "contradictions.resolve", true)?;
        update_status(
            self.pool,
            id,
            ContradictionStatus::Resolved,
            resolution,
            updated_at,
        )
    }

    /// Deletes a contradiction row through the ADR 0026 enforcement lattice.
    ///
    /// `policy` must compose
    /// [`TRANSITION_ACTOR_AUTHORITY_RULE_ID`],
    /// [`TRANSITION_RESOLUTION_EVIDENCE_RULE_ID`], and
    /// [`TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID`] contributors. Delete
    /// is destructive — ADR 0024 §1 prefers tombstoning — so the operator path
    /// must carry both attestation and current temporal authority before the
    /// row leaves the table.
    pub fn delete(&self, id: &ContradictionId, policy: &PolicyDecision) -> StoreResult<bool> {
        require_transition_policy(policy, "contradictions.delete", true)?;
        let changed = self.pool.execute(
            "DELETE FROM contradictions WHERE id = ?1;",
            params![id.to_string()],
        )?;
        Ok(changed > 0)
    }
}

#[derive(Debug)]
struct ContradictionRow {
    id: String,
    left_ref: String,
    right_ref: String,
    contradiction_type: String,
    status: String,
    interpretation: Option<String>,
    created_at: String,
    updated_at: String,
}

fn contradiction_row(row: &Row<'_>) -> rusqlite::Result<ContradictionRow> {
    Ok(ContradictionRow {
        id: row.get(0)?,
        left_ref: row.get(1)?,
        right_ref: row.get(2)?,
        contradiction_type: row.get(3)?,
        status: row.get(4)?,
        interpretation: row.get(5)?,
        created_at: row.get(6)?,
        updated_at: row.get(7)?,
    })
}

impl TryFrom<ContradictionRow> for ContradictionRecord {
    type Error = StoreError;

    fn try_from(row: ContradictionRow) -> StoreResult<Self> {
        Ok(Self {
            id: row.id.parse()?,
            left_ref: row.left_ref,
            right_ref: row.right_ref,
            contradiction_type: row.contradiction_type,
            status: parse_status(&row.status)?,
            interpretation: row.interpretation,
            created_at: DateTime::parse_from_rfc3339(&row.created_at)?.with_timezone(&Utc),
            updated_at: DateTime::parse_from_rfc3339(&row.updated_at)?.with_timezone(&Utc),
        })
    }
}

fn collect_records<F>(rows: rusqlite::MappedRows<'_, F>) -> StoreResult<Vec<ContradictionRecord>>
where
    F: FnMut(&Row<'_>) -> rusqlite::Result<ContradictionRow>,
{
    let mut records = Vec::new();
    for row in rows {
        records.push(row?.try_into()?);
    }
    Ok(records)
}

fn parse_status(status: &str) -> StoreResult<ContradictionStatus> {
    match status {
        "unresolved" => Ok(ContradictionStatus::Unresolved),
        "interpreted" => Ok(ContradictionStatus::Interpreted),
        "resolved" => Ok(ContradictionStatus::Resolved),
        other => Err(StoreError::Validation(format!(
            "invalid contradiction status {other}"
        ))),
    }
}

fn validate_record(record: &ContradictionRecord) -> StoreResult<()> {
    validate_not_empty("left_ref", &record.left_ref)?;
    validate_not_empty("right_ref", &record.right_ref)?;
    validate_not_empty("contradiction_type", &record.contradiction_type)?;
    if matches!(
        record.status,
        ContradictionStatus::Interpreted | ContradictionStatus::Resolved
    ) && record
        .interpretation
        .as_deref()
        .is_none_or(|value| value.trim().is_empty())
    {
        return Err(StoreError::Validation(
            "interpreted/resolved contradiction requires interpretation".into(),
        ));
    }
    Ok(())
}

fn update_status(
    pool: &Pool,
    id: &ContradictionId,
    status: ContradictionStatus,
    note: &str,
    updated_at: DateTime<Utc>,
) -> StoreResult<()> {
    validate_not_empty("interpretation", note)?;
    let changed = pool.execute(
        "UPDATE contradictions
         SET status = ?2, interpretation = ?3, updated_at = ?4
         WHERE id = ?1;",
        params![id.to_string(), status.wire(), note, updated_at.to_rfc3339()],
    )?;

    if changed == 0 {
        return Err(StoreError::Validation(format!(
            "contradiction {id} not found"
        )));
    }

    Ok(())
}

fn validate_not_empty(field: &str, value: &str) -> StoreResult<()> {
    if value.trim().is_empty() {
        return Err(StoreError::Validation(format!("{field} must not be empty")));
    }
    Ok(())
}

fn require_policy_final_outcome(policy: &PolicyDecision, surface: &str) -> StoreResult<()> {
    match policy.final_outcome {
        PolicyOutcome::Allow | PolicyOutcome::Warn | PolicyOutcome::BreakGlass => Ok(()),
        PolicyOutcome::Quarantine | PolicyOutcome::Reject => Err(StoreError::Validation(format!(
            "{surface} preflight: composed policy outcome {:?} blocks contradiction mutation",
            policy.final_outcome,
        ))),
    }
}

fn require_contributor_rule(policy: &PolicyDecision, rule_id: &str) -> StoreResult<()> {
    let contains_rule = policy
        .contributing
        .iter()
        .chain(policy.discarded.iter())
        .any(|contribution| contribution.rule_id.as_str() == rule_id);
    if contains_rule {
        Ok(())
    } else {
        Err(StoreError::Validation(format!(
            "policy decision missing required contributor `{rule_id}`; caller skipped ADR 0026 composition",
        )))
    }
}

fn require_transition_policy(
    policy: &PolicyDecision,
    surface: &str,
    require_operator_temporal_authority: bool,
) -> StoreResult<()> {
    require_policy_final_outcome(policy, surface)?;
    require_contributor_rule(policy, TRANSITION_ACTOR_AUTHORITY_RULE_ID)?;
    require_contributor_rule(policy, TRANSITION_RESOLUTION_EVIDENCE_RULE_ID)?;
    if require_operator_temporal_authority {
        require_contributor_rule(policy, TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID)?;
    }
    Ok(())
}

/// Build the `contradictions.transition.operator_temporal_authority`
/// contributor for a closing transition (`resolve` / `delete`) from an
/// ADR 0023 [`TemporalAuthorityReport`].
///
/// The contributor outcome mirrors the temporal authority's own
/// [`TemporalAuthorityReport::policy_decision`] outcome:
///
/// - `valid_now` → [`PolicyOutcome::Allow`]
/// - `valid_at_event_time && !valid_now` → [`PolicyOutcome::Quarantine`]
///   (historical signature, current use blocked)
/// - otherwise → [`PolicyOutcome::Reject`]
///
/// Callers should fold this contributor into the closing transition's
/// composition alongside the actor-authority and resolution-evidence
/// contributors.
#[must_use]
pub fn contradiction_transition_temporal_authority_contribution(
    report: &TemporalAuthorityReport,
) -> PolicyContribution {
    let outcome = if report.valid_now {
        PolicyOutcome::Allow
    } else if report.valid_at_event_time {
        PolicyOutcome::Quarantine
    } else {
        PolicyOutcome::Reject
    };
    let reason = if report.valid_now {
        "operator temporal authority is currently valid"
    } else if report.valid_at_event_time {
        "operator temporal authority is historical only; current use blocked"
    } else {
        "operator temporal authority was invalid at event time"
    };
    PolicyContribution::new(
        TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID,
        outcome,
        reason,
    )
    .expect("static contradiction temporal authority contribution is valid")
}

/// Build a [`PolicyDecision`] that satisfies [`ContradictionRepo::insert`] for
/// the happy path. Intended for tests and fixtures only.
///
/// Production callers MUST compose [`INSERT_SCOPE_VALIDITY_RULE_ID`] and
/// [`INSERT_UNRESOLVED_STATE_RULE_ID`] from real ADR 0024 evidence. This helper
/// is exposed unconditionally because integration test crates outside
/// `cortex-store` need the same fixture shape; the `_test_allow` suffix is the
/// contract that documents intent.
#[must_use]
pub fn insert_policy_decision_test_allow() -> PolicyDecision {
    use cortex_core::compose_policy_outcomes;
    compose_policy_outcomes(
        vec![
            PolicyContribution::new(
                INSERT_SCOPE_VALIDITY_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: contradiction scope validated",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                INSERT_UNRESOLVED_STATE_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: initial lifecycle state asserted",
            )
            .expect("static test contribution is valid"),
        ],
        None,
    )
}

/// Build a [`PolicyDecision`] that satisfies [`ContradictionRepo::interpret`]
/// for the happy path. Intended for tests and fixtures only; see
/// [`insert_policy_decision_test_allow`] for the production-caller contract.
#[must_use]
pub fn interpret_policy_decision_test_allow() -> PolicyDecision {
    use cortex_core::compose_policy_outcomes;
    compose_policy_outcomes(
        vec![
            PolicyContribution::new(
                TRANSITION_ACTOR_AUTHORITY_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: actor authority present",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                TRANSITION_RESOLUTION_EVIDENCE_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: interpretation evidence supplied",
            )
            .expect("static test contribution is valid"),
        ],
        None,
    )
}

/// Build a [`PolicyDecision`] that satisfies the closing-transition
/// (`resolve` / `delete`) entry points for the happy path. Intended for tests
/// and fixtures only.
///
/// Production callers MUST fold an honest
/// [`contradiction_transition_temporal_authority_contribution`] derived from a
/// real [`TemporalAuthorityReport`] into the composition instead of this
/// `Allow` placeholder.
#[must_use]
pub fn close_policy_decision_test_allow() -> PolicyDecision {
    use cortex_core::compose_policy_outcomes;
    compose_policy_outcomes(
        vec![
            PolicyContribution::new(
                TRANSITION_ACTOR_AUTHORITY_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: actor authority present",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                TRANSITION_RESOLUTION_EVIDENCE_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: resolution evidence supplied",
            )
            .expect("static test contribution is valid"),
            PolicyContribution::new(
                TRANSITION_OPERATOR_TEMPORAL_AUTHORITY_RULE_ID,
                PolicyOutcome::Allow,
                "test fixture: operator temporal authority current",
            )
            .expect("static test contribution is valid"),
        ],
        None,
    )
}