Receipts & Audit

pub struct ChioReceipt {
    pub id: String,                           // UUIDv7 recommended
    pub timestamp: u64,                       // Unix seconds
    pub capability_id: String,                // The capability that was exercised
    pub tool_server: String,
    pub tool_name: String,
    pub action: ToolCallAction,               // Parameters + parameter_hash
    pub decision: Decision,                   // The kernel verdict
    pub content_hash: String,                 // SHA-256 of evaluated content
    pub policy_hash: String,                  // SHA-256 of the applied policy
    pub evidence: Vec<GuardEvidence>,         // Per-guard records
    pub metadata: Option<serde_json::Value>,  // Stream / accounting details
    pub trust_level: TrustLevel,              // Mediation strength
    pub tenant_id: Option<String>,            // Multi-tenant isolation
    pub kernel_key: PublicKey,                // For verification without lookup
    pub algorithm: Option<SigningAlgorithm>,  // Absent means Ed25519
    pub signature: Signature,                 // Over canonical body
}

pub enum Decision {
    Allow,
    Deny { reason: String, guard: String },
    Cancelled { reason: String },
    Incomplete { reason: String },
}

pub enum TrustLevel {
    Mediated,    // Synchronous in-line mediation (strongest, default)
    Verified,    // Embedded kernel observed the call but did not mediate
                 // through a separate trust boundary
    Advisory,    // Shadow-mode / observability-only; caller may have
                 // proceeded regardless of the verdict
}

pub struct GuardEvidence {
    pub guard_name: String,           // e.g. "ForbiddenPathGuard"
    pub verdict: bool,                // true = passed, false = denied
    pub details: Option<String>,      // Optional diagnostic
}

pub trait SigningBackend: Send + Sync {
    fn algorithm(&self) -> SigningAlgorithm;
    fn public_key(&self) -> PublicKey;
    fn sign(&self, message: &[u8]) -> Result<Signature, Error>;
}

pub trait ReceiptStore: Send + Sync {
    fn append_chio_receipt(&self, receipt: &ChioReceipt) -> Result<(), ReceiptStoreError>;
    fn append_chio_receipt_returning_seq(
        &self,
        receipt: &ChioReceipt,
    ) -> Result<Option<u64>, ReceiptStoreError> {
        self.append_chio_receipt(receipt)?;
        Ok(None)
    }
    fn append_child_receipt(&self, receipt: &ChildRequestReceipt) -> Result<(), ReceiptStoreError>;

    // Checkpointing
    fn store_checkpoint(&self, _checkpoint: &KernelCheckpoint) -> Result<(), ReceiptStoreError>;
    fn load_checkpoint_by_seq(&self, _seq: u64) -> Result<Option<KernelCheckpoint>, ReceiptStoreError>;
    fn load_latest_checkpoint(&self) -> Result<Option<KernelCheckpoint>, ReceiptStoreError>;

    // Capability lineage, federated evidence, and lineage statements omitted here.
}

pub struct ReceiptQuery {
    pub capability_id: Option<String>,
    pub tool_server: Option<String>,
    pub tool_name: Option<String>,
    pub outcome: Option<String>,    // "allow" | "deny" | "cancelled" | "incomplete"
    pub since: Option<u64>,         // Unix seconds, inclusive
    pub until: Option<u64>,         // Unix seconds, inclusive
    pub min_cost: Option<u64>,      // Minor units
    pub max_cost: Option<u64>,
    pub cursor: Option<u64>,        // Forward pagination, exclusive
    pub limit: usize,               // Capped at MAX_QUERY_LIMIT (200)
    pub agent_subject: Option<String>,  // Hex-encoded subject key
    pub tenant_filter: Option<String>,
}

CREATE TABLE chio_tool_receipts (
    seq INTEGER PRIMARY KEY AUTOINCREMENT,
    receipt_id TEXT NOT NULL UNIQUE,
    timestamp INTEGER NOT NULL,
    capability_id TEXT NOT NULL,
    subject_key TEXT,
    issuer_key TEXT,
    grant_index INTEGER,
    tool_server TEXT NOT NULL,
    tool_name TEXT NOT NULL,
    decision_kind TEXT NOT NULL,
    policy_hash TEXT NOT NULL,
    content_hash TEXT NOT NULL,
    raw_json TEXT NOT NULL
);

CREATE INDEX idx_chio_tool_receipts_timestamp ON chio_tool_receipts(timestamp);
CREATE INDEX idx_chio_tool_receipts_capability ON chio_tool_receipts(capability_id);
CREATE INDEX idx_chio_tool_receipts_subject ON chio_tool_receipts(subject_key);
CREATE INDEX idx_chio_tool_receipts_grant ON chio_tool_receipts(capability_id, grant_index);
CREATE INDEX idx_chio_tool_receipts_tool ON chio_tool_receipts(tool_server, tool_name);
CREATE INDEX idx_chio_tool_receipts_decision ON chio_tool_receipts(decision_kind);

pub struct RetentionConfig {
    pub retention_days: u64,   // Default: 90
    pub max_size_bytes: u64,   // Default: 10 GB (10_737_418_240)
    pub archive_path: String,  // Default: "receipts-archive.sqlite3"
    pub tenant_id: Option<String>,
}

pub struct KernelCheckpointBody {
    pub schema: String,                    // "chio.checkpoint_statement.v1"
    pub checkpoint_seq: u64,               // Monotonic counter
    pub batch_start_seq: u64,
    pub batch_end_seq: u64,
    pub tree_size: usize,
    pub merkle_root: Hash,
    pub issued_at: u64,
    pub kernel_key: PublicKey,
    pub previous_checkpoint_sha256: Option<String>,
}

use chio_core_types::receipt::ChioReceipt;

let receipt: ChioReceipt = serde_json::from_str(json_blob)?;

// Step 1: signature.
assert!(receipt.verify_signature()?, "signature did not verify");

// Step 2: action hash matches parameters.
assert!(receipt.action.verify_hash()?, "parameter_hash drift");

// Step 3: expected kernel key.
assert_eq!(receipt.kernel_key, expected_kernel_pubkey);

// Step 4: optional - inclusion proof against a checkpoint root.
// Build a MerkleTree from the canonical bytes of the batch range,
// then verify ReceiptInclusionProof.path against batch_root.

println!("decision: {:?}", receipt.decision);
for ev in &receipt.evidence {
    println!("  {} -> verdict={}", ev.guard_name, ev.verdict);
}