zynk 1.0.1

use crate::profile::load_profile;
use crate::{CliError, CliResult};
use clap::Args;
use fs2::FileExt;
use rand::{rngs::OsRng, Rng};
use sha2::{Digest, Sha256};
use std::collections::HashSet;
use std::fs::{self, OpenOptions};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::PathBuf;

#[derive(Debug, Args)]
pub struct AuditArgs {
    #[arg(long)]
    pub profile: Option<PathBuf>,
    #[arg(
        long,
        default_value = "outputs",
        help = "runtime outputs root; pass <project>/outputs to write <project>/outputs/sessions/..."
    )]
    pub root: PathBuf,
    #[arg(long)]
    pub session_id: String,
    #[arg(long)]
    pub audit_id: Option<String>,
    #[arg(long)]
    pub previous_audit_id: Option<String>,
    #[arg(long)]
    pub timestamp: Option<String>,
    #[arg(
        long,
        help = "optional RFC3339 UTC deadline/expected-by for this record (ADR 027); advisory only"
    )]
    pub due: Option<String>,
    #[arg(long)]
    pub source_agent: String,
    #[arg(long)]
    pub source_address: String,
    #[arg(long)]
    pub target_agent: String,
    #[arg(long)]
    pub target_address: String,
    #[arg(long)]
    pub transport: String,
    #[arg(long)]
    pub workspace_id: String,
    #[arg(long)]
    pub transport_thread_id: Option<String>,
    #[arg(long)]
    pub mid: String,
    #[arg(long = "type")]
    pub record_type: String,
    #[arg(long)]
    pub mode: Option<String>,
    #[arg(long)]
    pub r#ref: Option<String>,
    #[arg(long)]
    pub re: Option<String>,
    #[arg(long, value_parser = ["agent", "operator", "helper-tool", "unknown"])]
    pub command_origin: String,
    #[arg(long)]
    pub payload: Option<String>,
    #[arg(long)]
    pub payload_file: Option<PathBuf>,
    #[arg(long, default_value = "hash-only")]
    pub payload_redaction_policy: String,
    #[arg(long)]
    pub payload_ref: Option<String>,
    #[arg(long)]
    pub sensitive_category: Option<String>,
    #[arg(long, default_value_t = 12)]
    pub excerpt_chars: usize,
    #[arg(
        long,
        help = "delivery proof state; use drafted for message-shaped text that was not sent"
    )]
    pub delivery_status: String,
    #[arg(long)]
    pub observed_by: String,
    #[arg(long, value_parser = ["transport", "agent", "operator", "helper-tool"])]
    pub verified_by: String,
    #[arg(
        long,
        help = "live DB path; by default the cwd .zynk/zynk.db is auto-created and the record is projected into it (ADR 028); --no-db forces file-only"
    )]
    pub db: Option<PathBuf>,
    #[arg(
        long,
        help = "force file-only; skip the DB projection even if a DB exists"
    )]
    pub no_db: bool,
    #[arg(
        long,
        help = "ADR 034: ALSO retain the full payload as recoverable ciphertext in the DB custody_vault (additive to the redacted corpus display); a retention failure is LOUD (nonzero), never a silent no-retain"
    )]
    pub retain_custody: bool,
    #[arg(
        long,
        help = "path to the operator-owned custody key file (default <db-dir>/custody.key or $ZYNK_CUSTODY_KEY_FILE); only used with --retain-custody"
    )]
    pub custody_key_file: Option<PathBuf>,
}

pub fn run(args: AuditArgs) -> CliResult<()> {
    let profile = load_profile(args.profile.as_deref())?;
    validate_audit_args(&args, &profile)?;
    // v1 M3a R1 P2: materialize --payload-file into the in-memory `payload` ONCE,
    // BEFORE any downstream read. Otherwise `write_audit_file` (hash) and
    // `retain_custody` (encrypt) each call `payload_from_args` and read the file
    // SEPARATELY — a source that diverges between reads (e.g. a FIFO) would bind a
    // different hash and ciphertext, silently producing an unrevealable record (the
    // D4 re-verify fails), which ADR 034 D7 forbids. validate_audit_args already
    // enforced payload XOR payload_file, so exactly one is set here. After this,
    // payload_file is None and payload holds the single-read bytes, so both the
    // hash/render and the custody encryption bind identical bytes.
    let mut args = args;
    if let Some(path) = args.payload_file.take() {
        let content = std::fs::read_to_string(&path).map_err(|error| {
            CliError::failure(format!(
                "failed to read payload file {}: {error}",
                path.display()
            ))
        })?;
        args.payload = Some(content);
    }
    let (audit_path, record) = write_audit_file(&args, &profile)?;
    project_record(args.db.as_deref(), args.no_db, &args.root, &record)?;
    // ADR 034 D7: opt-in full-payload custody. AFTER the file-first record is durable
    // (and projected), encrypt the FULL plaintext into the DB custody_vault — additive
    // to the redacted corpus display, which is UNCHANGED above. A retention failure
    // (key load / encrypt / vault insert) is ALWAYS LOUD: it returns a nonzero
    // CliError naming "record written but custody NOT retained", for BOTH the default
    // target AND an explicit `--db` (the operator explicitly asked to retain, so it
    // never soft-degrades to no-retain). The file record stays durable; the vault row
    // is absent.
    if args.retain_custody {
        let payload = payload_from_args(&args)?; // in-memory after the P2 materialize — identical bytes
        retain_custody_for(
            args.db.as_deref(),
            args.no_db,
            args.custody_key_file.as_deref(),
            &record,
            payload.as_bytes(),
        )
        .map_err(|error| {
            CliError::failure(format!(
                "{}; record written but custody NOT retained: {}",
                audit_path.display(),
                error.message
            ))
        })?;
    }
    println!("{}", audit_path.display());
    Ok(())
}

/// ADR 034 D7 (M3b shared helper): encrypt the FULL `payload_bytes` into the DB
/// custody_vault for `record`, under the operator key. Takes PRE-READ bytes so the
/// recorded `payload_hash` and the ciphertext bind IDENTICAL bytes (closes the M3a P2
/// TOCTOU for every producer by construction — no producer re-reads a payload source).
/// The CALLER wraps any Err into the LOUD nonzero "record written but custody NOT
/// retained" (D7). `--no-db` + retain must be rejected by the caller BEFORE the write
/// (the vault needs the DB).
pub(crate) fn retain_custody_for(
    db: Option<&std::path::Path>,
    no_db: bool,
    key_file: Option<&std::path::Path>,
    record: &crate::db::ImportedAuditRecord,
    payload_bytes: &[u8],
) -> CliResult<()> {
    let (db_path, _explicit) = crate::db::resolve_projection_target(db, no_db)
        .into_path_and_mode()
        .ok_or_else(|| {
            CliError::failure("custody retention requires a DB target (--no-db rejected)")
        })?;
    let key_path = crate::custody::resolve_key_path(key_file, &db_path);
    let key = crate::custody::load_or_create_key(&key_path)?;
    let (ciphertext, nonce) =
        crate::custody::encrypt(&key, &record.audit_id, &record.payload_hash, payload_bytes)?;
    crate::db::project_custody_vault(
        &db_path,
        &record.audit_id,
        &ciphertext,
        &nonce,
        crate::custody::CUSTODY_CIPHER_ID,
        crate::custody::CUSTODY_KEY_VERSION,
        &record.timestamp,
    )
}

/// Validate everything checkable before touching the filesystem (ADR 027:
/// invariants gate the file write). Reused by `send herdr`'s audited send to
/// validate BEFORE the irreversible transport act (ADR 029, hard part 1).
pub(crate) fn validate_audit_args(
    args: &AuditArgs,
    profile: &crate::profile::Profile,
) -> CliResult<()> {
    if args.payload.is_some() == args.payload_file.is_some() {
        return Err(CliError::usage(
            "exactly one of --payload or --payload-file is required",
        ));
    }
    // ADR 034 D7: custody is retained in the DB vault, so `--no-db` (file-only) is
    // incoherent with `--retain-custody`. Reject BEFORE any write — a requested
    // retention that can't be honored must fail loud, never silently no-retain.
    if args.retain_custody && args.no_db {
        return Err(CliError::usage(
            "--retain-custody cannot be combined with --no-db: custody is retained in the DB vault",
        ));
    }
    if args.excerpt_chars < 1 {
        return Err(CliError::usage("--excerpt-chars must be >= 1"));
    }
    if !profile
        .audit
        .delivery_status_enum
        .contains(&args.delivery_status)
    {
        return Err(CliError::usage(format!(
            "invalid delivery status: {}",
            args.delivery_status
        )));
    }
    if args.delivery_status == "sent" && args.verified_by == "agent" {
        return Err(CliError::usage(
            "delivery_status=sent requires transport, helper-tool, or operator verification",
        ));
    }
    // ADR 024 §1a + ADR 034 D8: a non-transport operator proof — every decision
    // record_type AND `reveal` — is observed/operator, never a delivered message.
    // Forbid delivery_status=sent on any such row so the invariant holds for ALL
    // audit producers (the structural `decide`/`reveal` paths hardcode observed, but
    // a raw `audit --type gate-decision|reveal --delivery-status sent --verified-by
    // helper-tool` would otherwise slip past the sent+agent guard above and forge a
    // "sent decision"/"sent reveal" proof). Pre-write gate: rejected with no side
    // effect.
    if crate::decision::is_non_transport_proof_record_type(&args.record_type)
        && args.delivery_status == "sent"
    {
        return Err(CliError::usage(
            "a non-transport operator proof (a decision record_type or `reveal`) must not be delivery_status=sent (ADR 024 §1a / ADR 034 D8: an observed/operator event, not a delivered message)",
        ));
    }
    // ADR 027 C4: validate --due with the real RFC3339 parser at the boundary
    // (the v5 GLOB trigger is only a defense-in-depth shape guard). Fail loud on
    // a malformed or impossible value rather than letting it reach an artifact.
    if let Some(due) = &args.due {
        if crate::timestamp::canonicalize(due).is_none() {
            return Err(CliError::usage(format!(
                "invalid due timestamp: {due} (expected RFC3339, e.g. 2026-06-01T12:00:00Z)"
            )));
        }
    }
    // ADR 027 C2/R1 P1: real-parser validate --timestamp BEFORE any file write.
    // A valid offset is preserved raw in the artifact (the DB projection
    // canonicalizes); a malformed or calendar-invalid value is rejected here.
    if let Some(timestamp) = &args.timestamp {
        if crate::timestamp::canonicalize(timestamp).is_none() {
            return Err(CliError::usage(format!(
                "invalid timestamp: {timestamp} (expected RFC3339, e.g. 2026-05-29T12:00:00Z)"
            )));
        }
    }
    if !profile
        .audit
        .redaction_policy_enum
        .contains(&args.payload_redaction_policy)
    {
        return Err(CliError::usage(format!(
            "invalid redaction policy: {}",
            args.payload_redaction_policy
        )));
    }
    Ok(())
}

/// Append the audit record to the session's `audit.md` under an exclusive lock
/// (file authority first, ADR 027). Returns the artifact path and the projection
/// record. Callers must `validate_audit_args` first.
pub(crate) fn write_audit_file(
    args: &AuditArgs,
    profile: &crate::profile::Profile,
) -> CliResult<(PathBuf, crate::db::ImportedAuditRecord)> {
    let audit_path = args
        .root
        .join("sessions")
        .join(&args.session_id)
        .join("audit.md");
    if let Some(parent) = audit_path.parent() {
        fs::create_dir_all(parent).map_err(|error| {
            CliError::failure(format!("failed to create {}: {error}", parent.display()))
        })?;
    }

    let mut handle = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(&audit_path)
        .map_err(|error| {
            CliError::failure(format!("failed to open {}: {error}", audit_path.display()))
        })?;
    handle.lock_exclusive().map_err(|error| {
        CliError::failure(format!("failed to lock {}: {error}", audit_path.display()))
    })?;
    let result = write_locked_record(args, profile, &mut handle);
    let unlock_result = handle.unlock();
    if let Err(error) = unlock_result {
        return Err(CliError::failure(format!(
            "failed to unlock {}: {error}",
            audit_path.display()
        )));
    }
    let record = result?;
    Ok((audit_path, record))
}

/// Project a written audit record into the live DB (ADR 027/028). Run after the
/// file is durable — never holds the file lock during DB I/O. The default target
/// auto-creates and soft-degrades on failure (warn; `db import` reconciles); an
/// explicit `--db` hard-fails. Reused by audited send.
pub(crate) fn project_record(
    db: Option<&std::path::Path>,
    no_db: bool,
    root: &std::path::Path,
    record: &crate::db::ImportedAuditRecord,
) -> CliResult<()> {
    if let Some((db_path, explicit)) =
        crate::db::resolve_projection_target(db, no_db).into_path_and_mode()
    {
        match crate::db::project_audit(&db_path, root, record) {
            Ok(crate::db::LiveAuditProjection::Gap { reason }) => eprintln!(
                "warning: audit DB projection gap (file written; db import will reconcile): {reason}"
            ),
            Ok(_) => {}
            // Explicit --db: an infra failure hard-fails (file already written, then nonzero).
            Err(error) if explicit => return Err(error),
            // Default: soft-degrade (file is the durable record; db import reconciles).
            Err(error) => eprintln!(
                "warning: audit DB projection skipped (file written): {}",
                error.message
            ),
        }
    }
    Ok(())
}

fn write_locked_record(
    args: &AuditArgs,
    profile: &crate::profile::Profile,
    handle: &mut std::fs::File,
) -> CliResult<crate::db::ImportedAuditRecord> {
    handle
        .seek(SeekFrom::Start(0))
        .map_err(|error| CliError::failure(format!("failed to read audit file: {error}")))?;
    let mut existing_content = String::new();
    handle
        .read_to_string(&mut existing_content)
        .map_err(|error| CliError::failure(format!("failed to read audit file: {error}")))?;
    let existing_ids = audit_ids_from_text(&existing_content);
    let existing_id_set = existing_ids.iter().cloned().collect::<HashSet<_>>();
    let audit_id = if let Some(audit_id) = &args.audit_id {
        if existing_id_set.contains(audit_id) {
            return Err(CliError::usage(format!("duplicate audit_id: {audit_id}")));
        }
        audit_id.clone()
    } else {
        generate_audit_id(&existing_id_set)?
    };
    let previous_audit_id = args
        .previous_audit_id
        .clone()
        .unwrap_or_else(|| last_audit_id(&existing_ids));
    let (record_text, imported) = render_record(args, profile, &previous_audit_id, &audit_id)?;

    handle
        .seek(SeekFrom::End(0))
        .map_err(|error| CliError::failure(format!("failed to append audit file: {error}")))?;
    if existing_content.is_empty() {
        write!(
            handle,
            "# Audit Trail: {}\n\nsession_id: {}\n\n## Records\n\n",
            args.session_id, args.session_id
        )
        .map_err(|error| CliError::failure(format!("failed to write audit header: {error}")))?;
    }
    writeln!(handle, "{record_text}")
        .map_err(|error| CliError::failure(format!("failed to write audit record: {error}")))?;
    Ok(imported)
}

fn render_record(
    args: &AuditArgs,
    profile: &crate::profile::Profile,
    previous_audit_id: &str,
    audit_id: &str,
) -> CliResult<(String, crate::db::ImportedAuditRecord)> {
    let mut policy = args.payload_redaction_policy.clone();
    if let Some(category) = &args.sensitive_category {
        if profile.audit.force_hash_only_categories.contains(category) {
            policy = "hash-only".to_string();
        }
    }
    let payload = payload_from_args(args)?;
    let payload_bytes = payload.as_bytes();
    let digest = Sha256::digest(payload_bytes);
    let timestamp = args
        .timestamp
        .clone()
        .unwrap_or_else(crate::timestamp::now_utc_seconds);
    let excerpt = payload_excerpt(&payload, args.excerpt_chars, &policy);
    // Canonicalize for the artifact (run() already rejected a malformed --due).
    let due = args
        .due
        .as_ref()
        .and_then(|due| crate::timestamp::canonicalize(due));
    let payload_hash = format!("sha256:{digest:x}");
    let content_size = payload_bytes.len();

    // Single source: the DB projection record is built from the SAME resolved
    // values the file is rendered from, so file and DB share one chain identity
    // (ADR 027 C6). previous_audit_id="none" means a chain head (NULL in the DB).
    let imported = crate::db::ImportedAuditRecord {
        audit_id: audit_id.to_string(),
        previous_audit_id: (previous_audit_id != "none").then(|| previous_audit_id.to_string()),
        timestamp: timestamp.clone(),
        source_agent_id: Some(args.source_agent.clone()),
        source_address: args.source_address.clone(),
        target_agent_id: Some(args.target_agent.clone()),
        target_address: args.target_address.clone(),
        transport: args.transport.clone(),
        workspace_id: args.workspace_id.clone(),
        session_id: args.session_id.clone(),
        mid: args.mid.clone(),
        record_type: args.record_type.clone(),
        command_origin: args.command_origin.clone(),
        mode: args.mode.clone(),
        r#ref: args.r#ref.clone(),
        re: args.re.clone(),
        payload_hash: payload_hash.clone(),
        payload_redaction_policy: policy.clone(),
        content_size: content_size as i64,
        delivery_status: args.delivery_status.clone(),
        observed_by: args.observed_by.clone(),
        verified_by: args.verified_by.clone(),
        due: due.clone(),
        // ADR 029 C6: same resolved excerpt the file artifact renders below, so
        // the DB corpus and the file carry identical content.
        payload_excerpt: excerpt.clone(),
    };

    let mut fields: Vec<(String, String)> = vec![
        ("audit_id".to_string(), audit_id.to_string()),
        (
            "previous_audit_id".to_string(),
            previous_audit_id.to_string(),
        ),
        ("timestamp".to_string(), timestamp),
        ("source_agent".to_string(), args.source_agent.clone()),
        ("source_address".to_string(), args.source_address.clone()),
        ("target_agent".to_string(), args.target_agent.clone()),
        ("target_address".to_string(), args.target_address.clone()),
        ("transport".to_string(), args.transport.clone()),
        ("workspace_id".to_string(), args.workspace_id.clone()),
        ("session_id".to_string(), args.session_id.clone()),
        ("mid".to_string(), args.mid.clone()),
        ("type".to_string(), args.record_type.clone()),
        ("command_origin".to_string(), args.command_origin.clone()),
        ("payload_hash".to_string(), payload_hash),
        ("payload_redaction_policy".to_string(), policy),
        ("content_size".to_string(), content_size.to_string()),
        ("delivery_status".to_string(), args.delivery_status.clone()),
        ("observed_by".to_string(), args.observed_by.clone()),
        ("verified_by".to_string(), args.verified_by.clone()),
    ];
    for (key, value) in [
        ("transport_thread_id", args.transport_thread_id.as_ref()),
        ("mode", args.mode.as_ref()),
        ("ref", args.r#ref.as_ref()),
        ("re", args.re.as_ref()),
        ("due", due.as_ref()),
        ("payload_ref", args.payload_ref.as_ref()),
        ("payload_excerpt", excerpt.as_ref()),
    ] {
        if let Some(value) = value {
            fields.push((key.to_string(), value.clone()));
        }
    }

    let record = fields
        .into_iter()
        .map(|(key, value)| format!("{key}={value}"))
        .collect::<Vec<_>>()
        .join("\n");
    Ok((format!("```text\n{record}\n```"), imported))
}

fn payload_from_args(args: &AuditArgs) -> CliResult<String> {
    if let Some(path) = &args.payload_file {
        return fs::read_to_string(path).map_err(|error| {
            CliError::failure(format!(
                "failed to read payload file {}: {error}",
                path.display()
            ))
        });
    }
    Ok(args.payload.clone().unwrap_or_default())
}

fn payload_excerpt(payload: &str, chars: usize, policy: &str) -> Option<String> {
    match policy {
        "hash-only" => None,
        "full" => Some(payload.to_string()),
        _ => {
            let count = payload.chars().count();
            if count <= chars * 2 {
                Some(payload.to_string())
            } else {
                let start = payload.chars().take(chars).collect::<String>();
                let end = payload
                    .chars()
                    .rev()
                    .take(chars)
                    .collect::<String>()
                    .chars()
                    .rev()
                    .collect::<String>();
                Some(format!("{start}...{end}"))
            }
        }
    }
}

fn audit_ids_from_text(content: &str) -> Vec<String> {
    content
        .lines()
        .filter_map(|line| line.trim().strip_prefix("audit_id="))
        .filter(|id| {
            id.chars()
                .all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit())
        })
        .map(str::to_string)
        .collect()
}

fn last_audit_id(existing_ids: &[String]) -> String {
    existing_ids
        .iter()
        .last()
        .cloned()
        .unwrap_or_else(|| "none".to_string())
}

fn generate_audit_id(existing_ids: &HashSet<String>) -> CliResult<String> {
    const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";
    let mut rng = OsRng;
    for _ in 0..100 {
        let audit_id = (0..6)
            .map(|_| {
                let index = rng.gen_range(0..ALPHABET.len());
                ALPHABET[index] as char
            })
            .collect::<String>();
        if !existing_ids.contains(&audit_id) {
            return Ok(audit_id);
        }
    }
    Err(CliError::usage(
        "could not generate unique audit_id after 100 attempts",
    ))
}