rpc/natives/

transaction.rs

//! Transaction-domain natives. Wraps `server::command::{CreateTransaction,
//! ListTransactions, GetTransaction, UpdateTransaction, DeleteTransaction}`.
//!
//! v1 binds the no-arg form of `list-transactions`. Filtering keyword args
//! (account / limit / offset / date_from / date_to) ride a follow-up slice
//! once the keyword-arg threading helper is shared across read commands.

use chrono::{DateTime, Utc};
use finance::split::Split;
use finance::tag::Tag;
use nomiscript::{Expr, Fraction, Reader};
use scripting::runtime::{
    alloc_entity_via_export, alloc_pair_chain, alloc_string_ref, read_string_arg,
};
#[cfg(test)]
use server::command::PaginationInfo;
use server::command::transaction::{
    CreateTransaction, DeleteTransaction, GetTransaction, GetTransactionTag, ListTransactions,
    SetTransactionTag, UpdateTransaction,
};
use server::command::{CmdError, CmdResult, FinanceEntity};
use uuid::Uuid;
use wasmtime::{AnyRef, ArrayRef, Caller, Linker, Rooted, StructRef, Val};

use crate::session::SessionData;

pub const REGISTERED_COMMANDS: &[&str] = &[
    "create-transaction",
    "list-transactions",
    "get-transaction",
    "update-transaction",
    "delete-transaction",
    "set-transaction-tag",
    "get-transaction-tag",
];

pub fn register(linker: &mut Linker<SessionData>) -> wasmtime::Result<()> {
    register_readonly(linker)?;
    register_mutators(linker)?;
    Ok(())
}

pub fn register_readonly(linker: &mut Linker<SessionData>) -> wasmtime::Result<()> {
    linker.func_wrap_async(
        "nomi",
        "transaction_list_transactions",
        |mut caller: Caller<'_, SessionData>,
         ()|
         -> Box<
            dyn std::future::Future<Output = wasmtime::Result<Option<Rooted<StructRef>>>> + Send,
        > {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let result = ListTransactions::new().user_id(user_id).run().await;
                let entries = list_transaction_entries("list-transactions", result)?;
                alloc_transaction_chain(&mut caller, entries).await
            })
        },
    )?;
    linker.func_wrap_async(
        "nomi",
        "transaction_get_transaction",
        |mut caller: Caller<'_, SessionData>,
         (id_arg,): (Option<Rooted<ArrayRef>>,)|
         -> Box<
            dyn std::future::Future<Output = wasmtime::Result<Option<Rooted<StructRef>>>> + Send,
        > {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let id = read_string_arg(&mut caller, id_arg)?;
                run_get_transaction(&mut caller, user_id, id).await
            })
        },
    )?;
    linker.func_wrap_async(
        "nomi",
        "transaction_get_transaction_tag",
        |mut caller: Caller<'_, SessionData>,
         (id_arg, name_arg): (Option<Rooted<ArrayRef>>, Option<Rooted<ArrayRef>>)|
         -> Box<
            dyn std::future::Future<Output = wasmtime::Result<Option<Rooted<ArrayRef>>>> + Send,
        > {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let id = read_string_arg(&mut caller, id_arg)?;
                let name = read_string_arg(&mut caller, name_arg)?;
                let value = run_get_transaction_tag(user_id, id, name).await?;
                Ok(Some(alloc_string_ref(&mut caller, value.as_bytes())?))
            })
        },
    )?;
    Ok(())
}

pub fn register_mutators(linker: &mut Linker<SessionData>) -> wasmtime::Result<()> {
    linker.func_wrap_async(
        "nomi",
        "transaction_delete_transaction",
        |mut caller: Caller<'_, SessionData>,
         (id_arg,): (Option<Rooted<ArrayRef>>,)|
         -> Box<dyn std::future::Future<Output = wasmtime::Result<i32>> + Send> {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let id = read_string_arg(&mut caller, id_arg)?;
                run_delete_transaction(user_id, id).await
            })
        },
    )?;
    linker.func_wrap_async(
        "nomi",
        "transaction_create_transaction",
        |mut caller: Caller<'_, SessionData>,
         (payload_arg,): (Option<Rooted<ArrayRef>>,)|
         -> Box<
            dyn std::future::Future<Output = wasmtime::Result<Option<Rooted<ArrayRef>>>> + Send,
        > {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let payload = read_string_arg(&mut caller, payload_arg)?;
                let id = run_create_transaction(user_id, payload).await?;
                Ok(Some(alloc_string_ref(&mut caller, id.as_bytes())?))
            })
        },
    )?;
    linker.func_wrap_async(
        "nomi",
        "transaction_update_transaction",
        |mut caller: Caller<'_, SessionData>,
         (payload_arg,): (Option<Rooted<ArrayRef>>,)|
         -> Box<
            dyn std::future::Future<Output = wasmtime::Result<Option<Rooted<ArrayRef>>>> + Send,
        > {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let payload = read_string_arg(&mut caller, payload_arg)?;
                let id = run_update_transaction(user_id, payload).await?;
                Ok(Some(alloc_string_ref(&mut caller, id.as_bytes())?))
            })
        },
    )?;
    linker.func_wrap_async(
        "nomi",
        "transaction_set_transaction_tag",
        |mut caller: Caller<'_, SessionData>,
         (id_arg, name_arg, value_arg): super::StringArgTriple|
         -> Box<dyn std::future::Future<Output = wasmtime::Result<i32>> + Send> {
            Box::new(async move {
                let user_id = caller.data().ctx().user_id;
                let id = read_string_arg(&mut caller, id_arg)?;
                let name = read_string_arg(&mut caller, name_arg)?;
                let value = read_string_arg(&mut caller, value_arg)?;
                run_set_transaction_tag(user_id, id, name, value).await
            })
        },
    )?;
    Ok(())
}

/// `set-transaction-tag` upsert (idempotent). Mirrors `set-split-tag`
/// and `set-account-tag` — i32 return = 1 on success.
async fn run_set_transaction_tag(
    user_id: Uuid,
    id_arg: Option<String>,
    name_arg: Option<String>,
    value_arg: Option<String>,
) -> wasmtime::Result<i32> {
    let raw = id_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("set-transaction-tag: missing or empty :transaction-id arg")
    })?;
    let transaction_id = Uuid::parse_str(&raw).map_err(|err| {
        wasmtime::Error::msg(format!("set-transaction-tag: invalid uuid '{raw}': {err}"))
    })?;
    let tag_name = name_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("set-transaction-tag: missing or empty :tag-name arg")
    })?;
    let tag_value = value_arg
        .ok_or_else(|| wasmtime::Error::msg("set-transaction-tag: missing :tag-value arg"))?;
    SetTransactionTag::new()
        .user_id(user_id)
        .transaction_id(transaction_id)
        .tag_name(tag_name)
        .tag_value(tag_value)
        .run()
        .await
        .map(|_| 1)
        .map_err(|err| wasmtime::Error::msg(format!("set-transaction-tag: {err}")))
}

/// `get-transaction-tag` lookup. Empty-string return on absence — same
/// shape as `get-split-tag`.
async fn run_get_transaction_tag(
    user_id: Uuid,
    id_arg: Option<String>,
    name_arg: Option<String>,
) -> wasmtime::Result<String> {
    let raw = id_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("get-transaction-tag: missing or empty :transaction-id arg")
    })?;
    let transaction_id = Uuid::parse_str(&raw).map_err(|err| {
        wasmtime::Error::msg(format!("get-transaction-tag: invalid uuid '{raw}': {err}"))
    })?;
    let tag_name = name_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("get-transaction-tag: missing or empty :tag-name arg")
    })?;
    match GetTransactionTag::new()
        .user_id(user_id)
        .transaction_id(transaction_id)
        .tag_name(tag_name)
        .run()
        .await
    {
        Ok(Some(CmdResult::String(s))) => Ok(s),
        Ok(Some(other)) => Err(wasmtime::Error::msg(format!(
            "get-transaction-tag: expected String, got {other:?}"
        ))),
        Ok(None) => Ok(String::new()),
        Err(err) => Err(wasmtime::Error::msg(format!("get-transaction-tag: {err}"))),
    }
}

/// Companion to create-transaction. Payload mirrors the create shape but
/// `:transaction-id` is required (the row being updated) and every other
/// field is optional — caller only supplies what they want changed.
/// Splits when present REPLACE the existing set; partial split updates
/// aren't representable in this slice (the server's UpdateTransaction
/// runner treats `splits` as a full-list replace).
async fn run_update_transaction(
    user_id: Uuid,
    payload_arg: Option<String>,
) -> wasmtime::Result<String> {
    let payload = payload_arg
        .filter(|s| !s.is_empty())
        .ok_or_else(|| wasmtime::Error::msg("update-transaction: missing or empty :payload arg"))?;
    let input = parse_update_transaction_payload(&payload)
        .map_err(|err| wasmtime::Error::msg(format!("update-transaction: {err}")))?;
    let mut runner = UpdateTransaction::new()
        .user_id(user_id)
        .transaction_id(input.transaction_id);
    if let Some(post_date) = input.post_date {
        runner = runner.post_date(post_date);
    }
    if let Some(enter_date) = input.enter_date {
        runner = runner.enter_date(enter_date);
    }
    if let Some(note) = input.note {
        runner = runner.note(note);
    }
    if let Some(splits) = input.splits {
        let entities: Vec<FinanceEntity> = splits
            .into_iter()
            .map(|mut s| {
                s.tx_id = input.transaction_id;
                FinanceEntity::Split(s)
            })
            .collect();
        runner = runner.splits(entities);
    }
    match runner.run().await {
        Ok(Some(CmdResult::Entity(FinanceEntity::Transaction(tx)))) => Ok(tx.id.to_string()),
        Ok(Some(other)) => Err(wasmtime::Error::msg(format!(
            "update-transaction: expected Transaction entity, got {other:?}"
        ))),
        Ok(None) => Err(wasmtime::Error::msg(
            "update-transaction: command returned no entity",
        )),
        Err(err) => Err(wasmtime::Error::msg(format!("update-transaction: {err}"))),
    }
}

#[derive(Debug)]
struct UpdateTransactionInput {
    transaction_id: Uuid,
    post_date: Option<DateTime<Utc>>,
    enter_date: Option<DateTime<Utc>>,
    note: Option<String>,
    splits: Option<Vec<Split>>,
}

fn parse_update_transaction_payload(src: &str) -> Result<UpdateTransactionInput, String> {
    let program = Reader::parse(src).map_err(|err| format!("payload parse: {err}"))?;
    let first = program
        .exprs
        .into_iter()
        .next()
        .ok_or_else(|| "payload empty".to_string())?;
    let plist = expect_plist(first, "payload")?;
    let tx_raw = take_plist_string(&plist, "transaction-id")?
        .ok_or_else(|| "payload: missing :transaction-id".to_string())?;
    let transaction_id = Uuid::parse_str(&tx_raw)
        .map_err(|err| format!("payload: invalid :transaction-id '{tx_raw}': {err}"))?;
    let post_date = match take_plist_string(&plist, "post-date")? {
        Some(raw) => Some(
            DateTime::parse_from_rfc3339(&raw)
                .map(|d| d.with_timezone(&Utc))
                .map_err(|err| format!("payload: invalid :post-date '{raw}': {err}"))?,
        ),
        None => None,
    };
    let enter_date = match take_plist_string(&plist, "enter-date")? {
        Some(raw) => Some(
            DateTime::parse_from_rfc3339(&raw)
                .map(|d| d.with_timezone(&Utc))
                .map_err(|err| format!("payload: invalid :enter-date '{raw}': {err}"))?,
        ),
        None => None,
    };
    let note = take_plist_string(&plist, "note")?;
    let splits = match take_plist_list(&plist, "splits")? {
        Some(list) => {
            if list.len() < 2 {
                return Err("payload: :splits must have at least two entries".into());
            }
            Some(
                list.into_iter()
                    .enumerate()
                    .map(|(idx, e)| parse_split_plist(e, idx))
                    .collect::<Result<Vec<_>, _>>()?,
            )
        }
        None => None,
    };
    Ok(UpdateTransactionInput {
        transaction_id,
        post_date,
        enter_date,
        note,
        splits,
    })
}

/// Parses the compound S-expr plist into the typed arguments
/// CreateTransaction needs. Keeps the wire format aligned with the rest
/// of the rpc surface — same Reader the envelope parser uses, same
/// keyword-plist shape readers see across natives. Skipping :prices /
/// :tags / :enter-date / :id for v1: the most common path (post a
/// single-commodity transaction with a couple splits and a note) lands;
/// the optional fields ride follow-up slices.
#[derive(Debug)]
struct CreateTransactionInput {
    id: Uuid,
    post_date: DateTime<Utc>,
    enter_date: DateTime<Utc>,
    note: Option<String>,
    splits: Vec<Split>,
}

async fn run_create_transaction(
    user_id: Uuid,
    payload_arg: Option<String>,
) -> wasmtime::Result<String> {
    let payload = payload_arg
        .filter(|s| !s.is_empty())
        .ok_or_else(|| wasmtime::Error::msg("create-transaction: missing or empty :payload arg"))?;
    let input = parse_create_transaction_payload(&payload)
        .map_err(|err| wasmtime::Error::msg(format!("create-transaction: {err}")))?;
    let mut splits: Vec<FinanceEntity> = input
        .splits
        .into_iter()
        .map(|mut s| {
            s.tx_id = input.id;
            FinanceEntity::Split(s)
        })
        .collect();
    let mut runner = CreateTransaction::new()
        .user_id(user_id)
        .id(input.id)
        .post_date(input.post_date)
        .enter_date(input.enter_date)
        .splits(std::mem::take(&mut splits));
    if let Some(note) = input.note {
        runner = runner.note(note);
    }
    match runner.run().await {
        Ok(Some(CmdResult::Entity(FinanceEntity::Transaction(tx)))) => Ok(tx.id.to_string()),
        Ok(Some(other)) => Err(wasmtime::Error::msg(format!(
            "create-transaction: expected Transaction entity, got {other:?}"
        ))),
        Ok(None) => Err(wasmtime::Error::msg(
            "create-transaction: command returned no entity",
        )),
        Err(err) => Err(wasmtime::Error::msg(format!("create-transaction: {err}"))),
    }
}

fn parse_create_transaction_payload(src: &str) -> Result<CreateTransactionInput, String> {
    let program = Reader::parse(src).map_err(|err| format!("payload parse: {err}"))?;
    let first = program
        .exprs
        .into_iter()
        .next()
        .ok_or_else(|| "payload empty".to_string())?;
    let plist = expect_plist(first, "payload")?;
    let post_date_raw = take_plist_string(&plist, "post-date")?
        .ok_or_else(|| "payload: missing :post-date".to_string())?;
    let post_date = DateTime::parse_from_rfc3339(&post_date_raw)
        .map(|d| d.with_timezone(&Utc))
        .map_err(|err| format!("payload: invalid :post-date '{post_date_raw}': {err}"))?;
    let enter_date = match take_plist_string(&plist, "enter-date")? {
        Some(raw) => DateTime::parse_from_rfc3339(&raw)
            .map(|d| d.with_timezone(&Utc))
            .map_err(|err| format!("payload: invalid :enter-date '{raw}': {err}"))?,
        None => Utc::now(),
    };
    let id = match take_plist_string(&plist, "id")? {
        Some(raw) => {
            Uuid::parse_str(&raw).map_err(|err| format!("payload: invalid :id '{raw}': {err}"))?
        }
        None => Uuid::new_v4(),
    };
    let note = take_plist_string(&plist, "note")?;
    let splits_list =
        take_plist_list(&plist, "splits")?.ok_or_else(|| "payload: missing :splits".to_string())?;
    if splits_list.len() < 2 {
        return Err("payload: :splits must have at least two entries".into());
    }
    let splits = splits_list
        .into_iter()
        .enumerate()
        .map(|(idx, expr)| parse_split_plist(expr, idx))
        .collect::<Result<Vec<_>, _>>()?;
    Ok(CreateTransactionInput {
        id,
        post_date,
        enter_date,
        note,
        splits,
    })
}

fn parse_split_plist(expr: Expr, idx: usize) -> Result<Split, String> {
    let plist = expect_plist(expr, &format!("split[{idx}]"))?;
    let account_raw = take_plist_string(&plist, "account-id")?
        .ok_or_else(|| format!("split[{idx}]: missing :account-id"))?;
    let account_id = Uuid::parse_str(&account_raw)
        .map_err(|err| format!("split[{idx}]: invalid :account-id '{account_raw}': {err}"))?;
    let commodity_raw = take_plist_string(&plist, "commodity-id")?
        .ok_or_else(|| format!("split[{idx}]: missing :commodity-id"))?;
    let commodity_id = Uuid::parse_str(&commodity_raw)
        .map_err(|err| format!("split[{idx}]: invalid :commodity-id '{commodity_raw}': {err}"))?;
    let value = take_plist_number(&plist, "value")?
        .ok_or_else(|| format!("split[{idx}]: missing :value"))?;
    Ok(Split {
        id: Uuid::new_v4(),
        tx_id: Uuid::nil(),
        account_id,
        commodity_id,
        reconcile_state: None,
        reconcile_date: None,
        value_num: *value.numer(),
        value_denom: *value.denom(),
        lot_id: None,
    })
}

/// Returns the (keyword, value) pairs the plist carries. The outer list
/// is interpreted as a flat plist: every even-index element must be a
/// `Keyword`; the following element is its value. Anything else is a
/// shape error.
fn expect_plist(expr: Expr, context: &str) -> Result<Vec<(String, Expr)>, String> {
    let items = match expr {
        Expr::List(items) => items,
        other => return Err(format!("{context}: expected plist, got {other:?}")),
    };
    if !items.len().is_multiple_of(2) {
        return Err(format!(
            "{context}: plist has odd number of elements ({})",
            items.len()
        ));
    }
    let mut out = Vec::with_capacity(items.len() / 2);
    let mut iter = items.into_iter();
    while let Some(key) = iter.next() {
        let key_name = match key {
            Expr::Keyword(name) => name,
            other => return Err(format!("{context}: expected :keyword, got {other:?}")),
        };
        let value = iter
            .next()
            .ok_or_else(|| format!("{context}: dangling :{key_name} without value"))?;
        out.push((key_name, value));
    }
    Ok(out)
}

fn take_plist_string(plist: &[(String, Expr)], key: &str) -> Result<Option<String>, String> {
    let upper = key.to_ascii_uppercase();
    match plist.iter().find(|(k, _)| k.eq_ignore_ascii_case(&upper)) {
        Some((_, Expr::String(s))) => Ok(Some(s.clone())),
        Some((_, Expr::Nil)) => Ok(None),
        Some((_, other)) => Err(format!(":{key} must be string, got {other:?}")),
        None => Ok(None),
    }
}

fn take_plist_number(plist: &[(String, Expr)], key: &str) -> Result<Option<Fraction>, String> {
    let upper = key.to_ascii_uppercase();
    match plist.iter().find(|(k, _)| k.eq_ignore_ascii_case(&upper)) {
        Some((_, Expr::Number(n))) => Ok(Some(*n)),
        Some((_, Expr::Nil)) => Ok(None),
        Some((_, other)) => Err(format!(":{key} must be number, got {other:?}")),
        None => Ok(None),
    }
}

fn take_plist_list(plist: &[(String, Expr)], key: &str) -> Result<Option<Vec<Expr>>, String> {
    let upper = key.to_ascii_uppercase();
    match plist.iter().find(|(k, _)| k.eq_ignore_ascii_case(&upper)) {
        Some((_, Expr::List(items))) => Ok(Some(items.clone())),
        Some((_, Expr::Nil)) => Ok(None),
        Some((_, other)) => Err(format!(":{key} must be list, got {other:?}")),
        None => Ok(None),
    }
}

/// Removes the transaction by UUID along with its splits, prices, and
/// owned tags. Not idempotent — server returns an error when the row
/// isn't there (vs remove-ssh-key which collapses to Ok). Returns `t`
/// on success.
async fn run_delete_transaction(user_id: Uuid, id_arg: Option<String>) -> wasmtime::Result<i32> {
    let raw = id_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("delete-transaction: missing or empty :transaction-id arg")
    })?;
    let transaction_id = Uuid::parse_str(&raw).map_err(|err| {
        wasmtime::Error::msg(format!("delete-transaction: invalid uuid '{raw}': {err}"))
    })?;
    DeleteTransaction::new()
        .user_id(user_id)
        .transaction_id(transaction_id)
        .run()
        .await
        .map(|_| 1)
        .map_err(|err| wasmtime::Error::msg(format!("delete-transaction: {err}")))
}

async fn run_get_transaction(
    caller: &mut Caller<'_, SessionData>,
    user_id: Uuid,
    id_arg: Option<String>,
) -> wasmtime::Result<Option<Rooted<StructRef>>> {
    let transaction_id = parse_transaction_id_arg(id_arg)?;
    let result = GetTransaction::new()
        .user_id(user_id)
        .transaction_id(transaction_id)
        .run()
        .await;
    let entries = list_transaction_entries("get-transaction", result)?;
    match entries.into_iter().next() {
        Some((id, note, post_date)) => Ok(Some(
            alloc_transaction_entity(caller, &id, note.as_deref(), Some(&post_date)).await?,
        )),
        None => Ok(None),
    }
}

/// Parses + validates the :transaction-id arg into a Uuid. Extracted so
/// the validation contract stays callable from unit tests that can't
/// construct a wasmtime `Caller`.
fn parse_transaction_id_arg(id_arg: Option<String>) -> wasmtime::Result<Uuid> {
    let raw = id_arg.filter(|s| !s.is_empty()).ok_or_else(|| {
        wasmtime::Error::msg("get-transaction: missing or empty :transaction-id arg")
    })?;
    Uuid::parse_str(&raw).map_err(|err| {
        wasmtime::Error::msg(format!("get-transaction: invalid uuid '{raw}': {err}"))
    })
}

/// Per-transaction (id, note-tag, post-date) triples. Pagination metadata
/// retires for v1; emacs clients consume the typed pair chain directly.
/// Filter-side `list-transactions :limit/:offset` keywords land in a
/// follow-up alongside the broader keyword-arg threading.
fn list_transaction_entries(
    name: &str,
    result: Result<Option<CmdResult>, CmdError>,
) -> wasmtime::Result<Vec<(String, Option<String>, String)>> {
    match result {
        Ok(Some(CmdResult::TaggedEntities { entities, .. })) => Ok(entities
            .into_iter()
            .filter_map(|(entity, tags)| match entity {
                FinanceEntity::Transaction(tx) => Some((
                    tx.id.to_string(),
                    tag_value(&tags, "note").map(str::to_string),
                    tx.post_date.to_rfc3339(),
                )),
                _ => None,
            })
            .collect()),
        Ok(Some(other)) => Err(wasmtime::Error::msg(format!(
            "{name}: expected TaggedEntities, got {other:?}"
        ))),
        Ok(None) => Ok(Vec::new()),
        Err(err) => Err(wasmtime::Error::msg(format!("{name}: {err}"))),
    }
}

async fn alloc_transaction_entity(
    caller: &mut Caller<'_, SessionData>,
    id: &str,
    note: Option<&str>,
    post_date: Option<&str>,
) -> wasmtime::Result<Rooted<StructRef>> {
    let id_ref = alloc_string_ref(caller, id.as_bytes())?;
    let note_ref = match note {
        Some(s) => Some(alloc_string_ref(caller, s.as_bytes())?),
        None => None,
    };
    let date_ref = match post_date {
        Some(s) => Some(alloc_string_ref(caller, s.as_bytes())?),
        None => None,
    };
    let args = [
        Val::AnyRef(Some(id_ref.to_anyref())),
        Val::AnyRef(note_ref.map(|r| r.to_anyref())),
        Val::AnyRef(date_ref.map(|r| r.to_anyref())),
    ];
    alloc_entity_via_export(caller, "alloc_transaction", &args).await
}

async fn alloc_transaction_chain(
    caller: &mut Caller<'_, SessionData>,
    entries: Vec<(String, Option<String>, String)>,
) -> wasmtime::Result<Option<Rooted<StructRef>>> {
    let mut anyrefs: Vec<Rooted<AnyRef>> = Vec::with_capacity(entries.len());
    for (id, note, post_date) in entries {
        let entity_ref =
            alloc_transaction_entity(caller, &id, note.as_deref(), Some(&post_date)).await?;
        anyrefs.push(entity_ref.to_anyref());
    }
    alloc_pair_chain(caller, anyrefs).await
}

/// Test-only legacy renderer; production paths now ship typed
/// `pair<transaction>` / `EntityRef(Transaction)` via the alloc helpers.
/// Retained for the existing format-assertion tests until A6 collapses
/// the streaming-string capture protocol.
#[cfg(test)]
fn format_tagged_transactions(
    entities: &[(
        FinanceEntity,
        std::collections::HashMap<String, FinanceEntity>,
    )],
    pagination: Option<&PaginationInfo>,
) -> String {
    let mut out = String::from("(:transactions (");
    for (idx, (entity, tags)) in entities.iter().enumerate() {
        if idx > 0 {
            out.push(' ');
        }
        match entity {
            FinanceEntity::Transaction(tx) => {
                out.push_str(&format!(
                    "(:id \"{}\" :post-date \"{}\" :enter-date \"{}\"",
                    tx.id,
                    tx.post_date.to_rfc3339(),
                    tx.enter_date.to_rfc3339()
                ));
                if let Some(note) = tag_value(tags, "note") {
                    out.push_str(&format!(" :note {}", quote_string(note)));
                }
                out.push(')');
            }
            other => {
                out.push_str(&format!("(:error \"unexpected entity {other:?}\")"));
            }
        }
    }
    out.push_str(") :pagination ");
    match pagination {
        Some(p) => out.push_str(&format!(
            "(:total {} :limit {} :offset {} :has-more {})",
            p.total_count,
            p.limit,
            p.offset,
            if p.has_more { "t" } else { "nil" }
        )),
        None => out.push_str("nil"),
    }
    out.push(')');
    out
}

fn tag_value<'a>(
    tags: &'a std::collections::HashMap<String, FinanceEntity>,
    key: &str,
) -> Option<&'a str> {
    tags.get(key).and_then(|t| match t {
        FinanceEntity::Tag(Tag { tag_value, .. }) => Some(tag_value.as_str()),
        _ => None,
    })
}

#[cfg(test)]
fn quote_string(s: &str) -> String {
    let mut q = String::with_capacity(s.len() + 2);
    q.push('"');
    for ch in s.chars() {
        match ch {
            '"' => q.push_str("\\\""),
            '\\' => q.push_str("\\\\"),
            other => q.push(other),
        }
    }
    q.push('"');
    q
}

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::TimeZone;
    use finance::transaction::Transaction;
    use std::collections::HashMap;
    use uuid::Uuid;

    fn tx_entity(id: Uuid) -> FinanceEntity {
        let post = chrono::Utc.with_ymd_and_hms(2026, 5, 1, 12, 0, 0).unwrap();
        let enter = chrono::Utc.with_ymd_and_hms(2026, 5, 2, 9, 30, 0).unwrap();
        FinanceEntity::Transaction(Transaction {
            id,
            post_date: post,
            enter_date: enter,
        })
    }

    #[test]
    fn format_empty_list_with_no_pagination() {
        assert_eq!(
            format_tagged_transactions(&[], None),
            "(:transactions () :pagination nil)"
        );
    }

    #[test]
    fn format_single_transaction_with_note_and_pagination() {
        let id = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000").unwrap();
        let mut tags = HashMap::new();
        tags.insert(
            "note".to_string(),
            FinanceEntity::Tag(Tag {
                id: Uuid::nil(),
                tag_name: "note".into(),
                tag_value: "groceries".into(),
                description: None,
            }),
        );
        let pagination = PaginationInfo {
            total_count: 1,
            limit: 20,
            offset: 0,
            has_more: false,
        };
        let out = format_tagged_transactions(&[(tx_entity(id), tags)], Some(&pagination));
        assert!(out.contains(":id \"550e8400-e29b-41d4-a716-446655440000\""));
        assert!(out.contains(":post-date \"2026-05-01T12:00:00+00:00\""));
        assert!(out.contains(":enter-date \"2026-05-02T09:30:00+00:00\""));
        assert!(out.contains(":note \"groceries\""));
        assert!(out.contains(":pagination (:total 1 :limit 20 :offset 0 :has-more nil)"));
    }

    #[test]
    fn format_transaction_without_tags_omits_note() {
        let id = Uuid::nil();
        let out = format_tagged_transactions(&[(tx_entity(id), HashMap::new())], None);
        assert!(out.contains(":id \"00000000-0000-0000-0000-000000000000\""));
        assert!(!out.contains(":note"));
        assert!(out.ends_with(":pagination nil)"));
    }

    #[test]
    fn parse_transaction_id_rejects_missing_arg() {
        let err = parse_transaction_id_arg(None).unwrap_err();
        assert!(err.to_string().contains("missing or empty"), "got: {err}");
    }

    #[test]
    fn parse_transaction_id_rejects_invalid_uuid() {
        let err = parse_transaction_id_arg(Some("not-a-uuid".into())).unwrap_err();
        assert!(err.to_string().contains("invalid uuid"), "got: {err}");
    }

    #[tokio::test]
    async fn run_delete_transaction_with_no_arg_emits_error() {
        let err = run_delete_transaction(Uuid::nil(), None).await.unwrap_err();
        assert!(err.to_string().contains("missing or empty"), "got: {err}");
    }

    #[tokio::test]
    async fn run_delete_transaction_with_invalid_uuid_emits_error() {
        let err = run_delete_transaction(Uuid::nil(), Some("not-uuid".into()))
            .await
            .unwrap_err();
        assert!(err.to_string().contains("invalid uuid"), "got: {err}");
    }

    #[test]
    fn parse_payload_minimal_two_splits() {
        let src = r#"(:post-date "2026-01-15T00:00:00Z"
            :splits ((:account-id "11111111-1111-1111-1111-111111111111"
                      :commodity-id "22222222-2222-2222-2222-222222222222"
                      :value -5000/100)
                     (:account-id "33333333-3333-3333-3333-333333333333"
                      :commodity-id "22222222-2222-2222-2222-222222222222"
                      :value 5000/100)))"#;
        let parsed = parse_create_transaction_payload(src).expect("parse");
        assert_eq!(parsed.splits.len(), 2);
        assert_eq!(parsed.splits[0].value_num, -50);
        assert_eq!(parsed.splits[0].value_denom, 1);
        assert_eq!(parsed.splits[1].value_num, 50);
    }

    #[test]
    fn parse_payload_picks_up_note() {
        let src = r#"(:post-date "2026-01-15T00:00:00Z"
            :note "groceries"
            :splits ((:account-id "11111111-1111-1111-1111-111111111111"
                      :commodity-id "22222222-2222-2222-2222-222222222222"
                      :value -1)
                     (:account-id "33333333-3333-3333-3333-333333333333"
                      :commodity-id "22222222-2222-2222-2222-222222222222"
                      :value 1)))"#;
        let parsed = parse_create_transaction_payload(src).expect("parse");
        assert_eq!(parsed.note.as_deref(), Some("groceries"));
    }

    #[test]
    fn parse_payload_rejects_missing_post_date() {
        let src = r#"(:splits ((:account-id "x" :commodity-id "y" :value 1)
                                (:account-id "x" :commodity-id "y" :value -1)))"#;
        let err = parse_create_transaction_payload(src).unwrap_err();
        assert!(err.contains(":post-date"), "got: {err}");
    }

    #[test]
    fn parse_payload_rejects_single_split() {
        let src = r#"(:post-date "2026-01-15T00:00:00Z"
                      :splits ((:account-id "x" :commodity-id "y" :value 1)))"#;
        let err = parse_create_transaction_payload(src).unwrap_err();
        assert!(err.contains("at least two"), "got: {err}");
    }

    #[tokio::test]
    async fn run_create_transaction_with_no_payload_emits_error() {
        let err = run_create_transaction(Uuid::nil(), None).await.unwrap_err();
        assert!(err.to_string().contains("missing or empty"), "got: {err}");
    }

    #[tokio::test]
    async fn run_create_transaction_with_garbage_payload_surfaces_parse_error() {
        let err = run_create_transaction(Uuid::nil(), Some("not-an-sexpr".into()))
            .await
            .unwrap_err();
        assert!(err.to_string().contains("create-transaction"), "got: {err}");
    }

    #[test]
    fn parse_update_payload_minimum_just_id() {
        let src = r#"(:transaction-id "550e8400-e29b-41d4-a716-446655440000")"#;
        let parsed = parse_update_transaction_payload(src).expect("parse");
        assert_eq!(
            parsed.transaction_id.to_string(),
            "550e8400-e29b-41d4-a716-446655440000"
        );
        assert!(parsed.note.is_none());
        assert!(parsed.splits.is_none());
    }

    #[test]
    fn parse_update_payload_rejects_missing_transaction_id() {
        let src = r#"(:note "x")"#;
        let err = parse_update_transaction_payload(src).unwrap_err();
        assert!(err.contains(":transaction-id"), "got: {err}");
    }

    #[test]
    fn parse_update_payload_carries_partial_fields() {
        let src = r#"(:transaction-id "550e8400-e29b-41d4-a716-446655440000"
                      :post-date "2026-05-11T12:00:00Z"
                      :note "edited")"#;
        let parsed = parse_update_transaction_payload(src).expect("parse");
        assert!(parsed.post_date.is_some());
        assert_eq!(parsed.note.as_deref(), Some("edited"));
        assert!(parsed.splits.is_none());
    }

    #[tokio::test]
    async fn run_update_transaction_with_no_payload_emits_error() {
        let err = run_update_transaction(Uuid::nil(), None).await.unwrap_err();
        assert!(err.to_string().contains("missing or empty"), "got: {err}");
    }

    #[test]
    fn format_pagination_has_more_emits_t() {
        let pagination = PaginationInfo {
            total_count: 100,
            limit: 20,
            offset: 0,
            has_more: true,
        };
        let out = format_tagged_transactions(&[], Some(&pagination));
        assert!(out.contains(":has-more t)"));
    }
}