proofborne-core 0.1.0

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;
use uuid::Uuid;

use crate::{AssuranceLevel, SCHEMA_VERSION, hash_bytes};

/// Semantic category of one provenance-bound context statement.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ContextKind {
    /// Runtime-observed tool, process, Git, or completion evidence.
    Observation,
    /// Unverified model-authored conclusion.
    Assertion,
    /// Explicit human or runtime policy decision.
    Decision,
    /// User-authored durable preference.
    UserPreference,
    /// Statement imported from an external source.
    External,
}

/// Provenance anchor for one context statement.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ContextSource {
    /// Session whose causal event introduced this statement.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session_id: Option<Uuid>,
    /// Hash of the source event in the session event chain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event_id: Option<String>,
    /// Source event sequence in the session event chain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event_seq: Option<u64>,
    /// Runtime evidence represented by this context item.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub evidence_id: Option<Uuid>,
    /// Runtime generation observed by the source.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub workspace_generation: Option<u64>,
    /// Canonical workspace digest observed by the source.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub state_binding: Option<String>,
    /// Optional external provenance URI.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub external_uri: Option<String>,
}

/// Scope in which a context statement may be retrieved.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ContextScope {
    /// Secret-free digest of the canonical workspace identity.
    pub workspace_id: String,
    /// Optional repository identity supplied by a trusted runtime integration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub repository: Option<String>,
    /// Optional branch identity supplied by a trusted runtime integration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub branch: Option<String>,
    /// Workspace-relative path, when the statement is path-scoped.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// Language symbol, when the statement is symbol-scoped.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub symbol: Option<String>,
    /// Task contract that caused the observation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub task_contract_id: Option<Uuid>,
}

/// Authority that produced a context statement.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ContextAuthority {
    /// Stable producer identity.
    pub producer: String,
    /// Assurance boundary inherited from the source observation.
    pub assurance_level: AssuranceLevel,
    /// Whether the producer and classification are runtime-owned.
    pub runtime_owned: bool,
}

/// Public indication that sensitive input was removed before persistence.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SecretTaint {
    /// No configured secret matched the persisted public statement.
    #[default]
    None,
    /// Sensitive material matched and only a redacted statement was retained.
    Redacted,
}

/// Immutable, content-addressed context statement.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct ContextItem {
    /// Public schema identifier.
    pub schema_version: String,
    /// Stable item identifier.
    pub id: Uuid,
    /// Statement category.
    pub kind: ContextKind,
    /// Public, redacted statement body.
    pub content: String,
    /// BLAKE3 digest of the exact UTF-8 statement body.
    pub content_digest: String,
    /// Causal provenance.
    pub source: ContextSource,
    /// Retrieval boundary.
    pub scope: ContextScope,
    /// Source observation time.
    pub observed_at: DateTime<Utc>,
    /// Producer authority.
    pub authority: ContextAuthority,
    /// Sensitive-data handling result.
    #[serde(default)]
    pub secret_taint: SecretTaint,
    /// Public structured attributes; never used as verification evidence by itself.
    #[serde(default)]
    pub attributes: Value,
}

impl ContextItem {
    /// Creates one runtime-owned observation from a redacted evidence statement.
    #[must_use]
    pub fn runtime_observation(
        content: impl Into<String>,
        source: ContextSource,
        scope: ContextScope,
        observed_at: DateTime<Utc>,
        authority: ContextAuthority,
        secret_taint: SecretTaint,
        attributes: Value,
    ) -> Self {
        let content = content.into();
        Self {
            schema_version: SCHEMA_VERSION.to_owned(),
            id: Uuid::now_v7(),
            kind: ContextKind::Observation,
            content_digest: hash_bytes(content.as_bytes()),
            content,
            source,
            scope,
            observed_at,
            authority,
            secret_taint,
            attributes,
        }
    }

    /// Validates public shape, digest, provenance, and scope invariants.
    pub fn validate(&self) -> Result<(), ContextError> {
        if self.schema_version != SCHEMA_VERSION {
            return Err(ContextError::UnsupportedSchema(self.schema_version.clone()));
        }
        if self.content.trim().is_empty() {
            return Err(ContextError::EmptyContent);
        }
        if self.content_digest != hash_bytes(self.content.as_bytes()) {
            return Err(ContextError::ContentDigest);
        }
        if !valid_digest(&self.scope.workspace_id) {
            return Err(ContextError::WorkspaceIdentity);
        }
        if self.authority.producer.trim().is_empty() {
            return Err(ContextError::EmptyProducer);
        }
        if !self.attributes.is_object() {
            return Err(ContextError::Attributes);
        }
        match (&self.source.event_id, self.source.event_seq) {
            (Some(event_id), Some(_)) if valid_digest(event_id) => {}
            (None, None) => {}
            _ => return Err(ContextError::EventAnchor),
        }
        if self.source.state_binding.is_some() != self.source.workspace_generation.is_some() {
            return Err(ContextError::WorkspaceAnchor);
        }
        if self
            .source
            .state_binding
            .as_deref()
            .is_some_and(|binding| !valid_digest(binding))
        {
            return Err(ContextError::WorkspaceAnchor);
        }
        if self.authority.runtime_owned
            && (self.source.session_id.is_none()
                || self.source.event_id.is_none()
                || self.source.evidence_id.is_none())
        {
            return Err(ContextError::RuntimeProvenance);
        }
        if self
            .scope
            .path
            .as_deref()
            .is_some_and(|path| !valid_relative_scope_path(path))
        {
            return Err(ContextError::ScopePath);
        }
        Ok(())
    }
}

/// Durable retrieval lifecycle of one context item.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum MemoryStatus {
    /// Bound to the latest workspace state observed by the runtime.
    Current,
    /// Not bound to a workspace state and therefore never current evidence.
    Unbound,
    /// Invalidated by a later observed workspace state.
    Stale,
    /// Replaced by a newer context item.
    Superseded,
    /// Explicitly invalidated by the runtime.
    Invalidated,
}

/// Runtime-owned reason a memory item ceased to be current.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ContextInvalidationReason {
    /// A different canonical workspace state was observed.
    WorkspaceChanged,
    /// A newer item explicitly replaced this item.
    Superseded,
    /// Runtime policy rejected continued use.
    Policy,
    /// Source provenance failed validation.
    Provenance,
}

/// Durable invalidation receipt.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ContextInvalidation {
    /// Runtime-owned invalidation reason.
    pub reason: ContextInvalidationReason,
    /// Time the invalidation was persisted.
    pub at: DateTime<Utc>,
    /// Workspace epoch at invalidation time.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observed_workspace_generation: Option<u64>,
    /// Workspace digest that caused invalidation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observed_state_binding: Option<String>,
    /// Newer context item when supersession caused invalidation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source_context_id: Option<Uuid>,
}

/// Persisted context plus its runtime-owned lifecycle state.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct MemoryItem {
    /// Public schema identifier.
    pub schema_version: String,
    /// Immutable context payload.
    pub context: ContextItem,
    /// Current retrieval lifecycle.
    pub status: MemoryStatus,
    /// Newer context item, when superseded.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub superseded_by: Option<Uuid>,
    /// Runtime-owned invalidation receipt.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub invalidation: Option<ContextInvalidation>,
    /// First durable persistence time.
    pub stored_at: DateTime<Utc>,
    /// Last lifecycle transition time.
    pub updated_at: DateTime<Utc>,
}

impl MemoryItem {
    /// Validates the context and lifecycle consistency.
    pub fn validate(&self) -> Result<(), ContextError> {
        if self.schema_version != SCHEMA_VERSION {
            return Err(ContextError::UnsupportedSchema(self.schema_version.clone()));
        }
        self.context.validate()?;
        if self.updated_at < self.stored_at {
            return Err(ContextError::TimestampOrder);
        }
        match self.status {
            MemoryStatus::Current => {
                if self.context.source.state_binding.is_none()
                    || self.invalidation.is_some()
                    || self.superseded_by.is_some()
                {
                    return Err(ContextError::Lifecycle);
                }
            }
            MemoryStatus::Unbound => {
                if self.context.source.state_binding.is_some()
                    || self.invalidation.is_some()
                    || self.superseded_by.is_some()
                {
                    return Err(ContextError::Lifecycle);
                }
            }
            MemoryStatus::Stale | MemoryStatus::Invalidated => {
                if self.invalidation.is_none() || self.superseded_by.is_some() {
                    return Err(ContextError::Lifecycle);
                }
            }
            MemoryStatus::Superseded => {
                if self.invalidation.is_none() || self.superseded_by.is_none() {
                    return Err(ContextError::Lifecycle);
                }
            }
        }
        Ok(())
    }
}

fn valid_digest(value: &str) -> bool {
    value.len() == 64
        && value
            .bytes()
            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}

fn valid_relative_scope_path(path: &str) -> bool {
    !path.is_empty()
        && !path.starts_with('/')
        && !path.starts_with('\\')
        && !path.contains(':')
        && !path
            .split(['/', '\\'])
            .any(|component| component.is_empty() || component == "." || component == "..")
}

/// Context contract validation failure.
#[derive(Debug, Clone, Error, PartialEq, Eq)]
pub enum ContextError {
    /// Unsupported public schema identifier.
    #[error("unsupported context schema: {0}")]
    UnsupportedSchema(String),
    /// Statement body is empty.
    #[error("context content must not be empty")]
    EmptyContent,
    /// Statement digest does not match its body.
    #[error("context content digest is invalid")]
    ContentDigest,
    /// Workspace identity is not a canonical digest.
    #[error("context workspace identity is invalid")]
    WorkspaceIdentity,
    /// Producer identity is empty.
    #[error("context producer must not be empty")]
    EmptyProducer,
    /// Attributes are not a JSON object.
    #[error("context attributes must be an object")]
    Attributes,
    /// Event sequence and event digest are incomplete or malformed.
    #[error("context event anchor is invalid")]
    EventAnchor,
    /// Workspace generation and state binding are incomplete or malformed.
    #[error("context workspace anchor is invalid")]
    WorkspaceAnchor,
    /// Runtime-owned statements lack causal session/event/evidence provenance.
    #[error("runtime-owned context lacks causal provenance")]
    RuntimeProvenance,
    /// Path scope is absolute, ambiguous, or traverses a parent.
    #[error("context path scope must be a normalized workspace-relative path")]
    ScopePath,
    /// Updated timestamp precedes initial persistence.
    #[error("memory lifecycle timestamp order is invalid")]
    TimestampOrder,
    /// Status, invalidation, binding, and supersession disagree.
    #[error("memory lifecycle state is inconsistent")]
    Lifecycle,
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use super::*;

    fn item() -> ContextItem {
        ContextItem::runtime_observation(
            "cargo test passed",
            ContextSource {
                session_id: Some(Uuid::now_v7()),
                event_id: Some("a".repeat(64)),
                event_seq: Some(4),
                evidence_id: Some(Uuid::now_v7()),
                workspace_generation: Some(2),
                state_binding: Some("b".repeat(64)),
                external_uri: None,
            },
            ContextScope {
                workspace_id: "c".repeat(64),
                repository: None,
                branch: None,
                path: Some("src/lib.rs".to_owned()),
                symbol: None,
                task_contract_id: Some(Uuid::now_v7()),
            },
            Utc::now(),
            ContextAuthority {
                producer: "verify.exec".to_owned(),
                assurance_level: AssuranceLevel::Observed,
                runtime_owned: true,
            },
            SecretTaint::None,
            json!({"success": true}),
        )
    }

    #[test]
    fn runtime_context_and_current_memory_validate() {
        let context = item();
        context.validate().unwrap();
        let now = Utc::now();
        let memory = MemoryItem {
            schema_version: SCHEMA_VERSION.to_owned(),
            context,
            status: MemoryStatus::Current,
            superseded_by: None,
            invalidation: None,
            stored_at: now,
            updated_at: now,
        };
        memory.validate().unwrap();
    }

    #[test]
    fn tampered_content_and_parent_scope_are_rejected() {
        let mut context = item();
        context.content.push('!');
        assert_eq!(context.validate(), Err(ContextError::ContentDigest));
        let mut context = item();
        context.scope.path = Some("../secret".to_owned());
        assert_eq!(context.validate(), Err(ContextError::ScopePath));
    }

    #[test]
    fn current_memory_requires_a_workspace_binding() {
        let mut context = item();
        context.source.workspace_generation = None;
        context.source.state_binding = None;
        let now = Utc::now();
        let memory = MemoryItem {
            schema_version: SCHEMA_VERSION.to_owned(),
            context,
            status: MemoryStatus::Current,
            superseded_by: None,
            invalidation: None,
            stored_at: now,
            updated_at: now,
        };
        assert_eq!(memory.validate(), Err(ContextError::Lifecycle));
    }
    #[test]
    fn context_retrieval_is_not_default_task_evidence() {
        let requirement = crate::EvidenceRequirement::task();
        assert!(
            !requirement
                .allowed_kinds
                .contains(&crate::EvidenceKind::Context)
        );
    }
}