calternal_money::import

Deterministic source-to-Money writer for Actual and YNAB adapters (#462).

The format adapters build ImportSource from one export. This module assigns stable IDs, writes every owned Money file in one pass, then reads the files back through the same codec and budget engine used by the app. Equal-date rows keep source order because it decides Card payment allocations. Month rows move into their final files before Ledger projection to limit memory. Amounts stay in exact minor units. Source names and transaction text never enter logs or error messages. #1130 retains closed Accounts and separate notes/status properties. Split children, transfer legs and Tracking categories use inert evidence without another posting.

Source: crates/calternal-money/src/import.rs

Structs

ImportAccount

pub struct ImportAccount

One source account, including an optional starting balance row.

Fields

• pub closed: bool: Closed Accounts keep history and balances but leave active lists (#1130).
• pub needs_kind: bool: A suspected Card without a source type needs a review choice (#1130).
• pub source_id: String: Stable account identity in the source export.
• pub name: String: Account label from the source export.
• pub kind: AccountKind: The selected Money account kind.
• pub currency: String: Currency used by this account.
• pub payment_category_source_id: Option<String>: Source Category ID for a Card account’s payment Category, when known.
• pub opening_balance: Option<ImportOpeningBalance>: Starting balance when the source has no opening-balance transaction.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:27

ImportAccountBalance

pub struct ImportAccountBalance

One source Account balance at one month end.

Fields

• pub account_source_id: String: Source Account identity.
• pub month: String: Calendar month in YYYY-MM form.
• pub amount: Minor: Exact balance in the Budget currency’s minor units.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:225

ImportAssignment

pub struct ImportAssignment

One monthly Category assignment.

Fields

• pub category_source_id: String: Source Category ID.
• pub month: String: Calendar month YYYY-MM.
• pub amount: Minor: Exact assigned amount in budget minor units.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:76

ImportCategory

pub struct ImportCategory

One source Category, including the format fields the source can express.

Fields

• pub source_text: Vec<String>: Source template, goal and note text, encoded losslessly (#1130).
• pub source_id: String: Stable Category identity in the source export.
• pub group: String: Category group label.
• pub name: String: Category label.
• pub kind: CategoryKind: Money Category kind selected by the adapter.
• pub hidden: bool: True when the source hides this Category or its group.
• pub target: Option<Minor>: Exact fixed monthly target, if the source has one.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:57

ImportCategoryMonth

pub struct ImportCategoryMonth

One source Category’s exact numbers for one month.

Fields

• pub category_source_id: String: Source Category identity.
• pub month: String: Calendar month in YYYY-MM form.
• pub assigned: Minor: Exact amount assigned in that month.
• pub activity: Minor: Exact source activity in that month.
• pub balance: Minor: Exact month-end Category balance.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:236

ImportCheckSummary

pub struct ImportCheckSummary

Aggregate pass and fail counts for one independent import check.

Fields

• pub check: String: Stable check name; it contains no source labels or values.
• pub passed: usize: Number of exact values that match.
• pub failed: usize: Number of exact values that differ or are missing.

Implements: Clone, Debug, Eq, PartialEq, Serialize

Source: crates/calternal-money/src/import.rs:260

ImportGap

pub struct ImportGap

One source-format feature counted for the review, including preserved fields.

Fields

• pub feature: String: Stable feature name. It never contains source text.
• pub count: usize: Number of source items affected by this gap.

Implements: Clone, Debug, Eq, PartialEq, Serialize

Source: crates/calternal-money/src/import.rs:178

ImportOpeningBalance

pub struct ImportOpeningBalance

One starting balance that the renderer writes as a transaction row.

Fields

• pub date: String: Calendar date for the source opening balance.
• pub amount: Minor: Exact amount in the account currency’s minor units.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:48

ImportPlan

pub struct ImportPlan

Files for a memory-backed plan and the safe aggregate report with its small sample.

Fields

• pub account_kind_questions: Vec<(String, String)>: Accounts that still need a Cash or Card choice before publication (#1130).
• pub files: BTreeMap<String: File name to full Markdown content. A staged Actual plan leaves this map empty because its caller stores each generated file as it completes.
• pub summary: ImportSummary: Aggregate counts for the preview.
• pub gaps: Vec<ImportGap>: Source features that did not map to distinct Money fields.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:357

ImportPreviewRow

pub struct ImportPreviewRow

One exact, bounded transaction sample shown before the User confirms.

Fields

• pub date: String: Calendar date in YYYY-MM-DD form.
• pub account: String: Source Account label, shortened for predictable preview memory.
• pub amount: String: Exact amount formatted at the source currency scale.
• pub currency: String: ISO 4217 currency code.
• pub payee: String: Payee, shortened to 120 characters for predictable preview memory.

Implements: Clone, Debug, Eq, PartialEq, Serialize

Source: crates/calternal-money/src/import.rs:304

ImportReadyToAssign

pub struct ImportReadyToAssign

One exact source Ready to Assign amount for one month.

Fields

• pub month: String: Calendar month in YYYY-MM form.
• pub amount: Minor: Exact month-end Ready to Assign amount.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:251

ImportSource

pub struct ImportSource

A complete normalized export, ready for deterministic Money rendering.

Fields

• pub budget_id: String: Stable ID for the new Budget folder’s Money files.
• pub title: String: Budget title written to Budget.md.
• pub currency: String: ISO 4217 Budget currency.
• pub accounts: Vec<ImportAccount>: Accounts in source order.
• pub categories: Vec<ImportCategory>: Categories in source order.
• pub assignments: Vec<ImportAssignment>: Monthly assignments in source order.
• pub transactions: Vec<ImportTransaction>: Transactions after the adapter collapses split parents and paired transfers to one Money row.
• pub verification: ImportVerification: Source-side totals captured by the adapter before Markdown generation.
• pub ready_to_assign_adjustment_category_source_id: Option<String>: Adjustment Category used only when source Ready to Assign totals need reconciliation with Money’s derived budget behavior.
• pub gaps: Vec<ImportGap>: Source-to-format gaps, counted by the adapter.

Implements: Clone, Debug

ImportSource::stream_renderer

pub fn stream_renderer(&self, needs_uncategorized: bool) -> Result<ImportStreamRenderer<'_>>

Start an incremental renderer after an adapter has determined whether any streamed row needs the shared Uncategorized Category (#462, DESIGN §48).

ImportSource::render

pub fn render(&self) -> Result<ImportPlan>

Render and re-project a complete new Budget using stable source IDs.

This is a pure operation: it does not write to disk or print source rows. The returned files have passed the Money codec and arithmetic checks before an adapter exposes them for preview (#462, DESIGN §48).

ImportSource::render_with_progress

pub fn render_with_progress(
        &self,
        mut progress: impl FnMut(usize, usize) -> Result<()>,
    ) -> Result<ImportPlan>

Render a complete Budget and report bounded checkpoints while rows are converted. The callback may stop the operation, which lets a server enforce the Money import time and cancel rules (#462, DESIGN §48); file order and generated bytes stay identical to render.

ImportSource::render_with_progress_and_check

pub fn render_with_progress_and_check(
        &self,
        mut progress: impl FnMut(usize, usize) -> Result<()>,
        mut check: impl FnMut() -> Result<()>,
    ) -> Result<ImportPlan>

Render with source-row progress and bounded cancellation checks during generated-file parsing and projection (#462, DESIGN §48).

Source: crates/calternal-money/src/import.rs:187

ImportSplit

pub struct ImportSplit

One split child in a source transaction.

Fields

• pub category_source_id: String: Source Category ID for this leg.
• pub amount: Minor: Exact amount in the transaction currency’s minor units.
• pub currency: String: Currency used by this split amount.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:87

ImportStreamRenderer

pub struct ImportStreamRenderer<'a>

Incremental Markdown writer for adapters that read large transaction tables as prepared row streams. It keeps shared metadata and stable IDs, while the caller owns only the current month file and aggregate checks (#462, DESIGN §48).

ImportStreamRenderer::base_files

pub fn base_files(&self) -> BTreeMap<String, String>

Return the shared Budget and Account files prepared from validated source metadata (#462, DESIGN §48).

ImportStreamRenderer::new_month_file

pub fn new_month_file(&self, month: &str) -> Result<String>

Start one empty month document with the stable Budget identity.

ImportStreamRenderer::account_id

pub fn account_id(&self, source_id: &str) -> Option<&str>

Find the stable Money Account ID used by generated transaction links.

ImportStreamRenderer::category_id

pub fn category_id(&self, source_id: &str) -> Option<&str>

Find the stable Money Category ID used by generated transaction links.

ImportStreamRenderer::render_source_transaction

pub fn render_source_transaction(&mut self, row: &ImportTransaction) -> Result<String>

Render one source transaction and update aggregate preview counts. The source ID must be unique and already be a lowercase stable slug; the Actual adapter verifies both without retaining a million-row ID set (#462, DESIGN §48).

ImportStreamRenderer::render_generated_transaction

pub fn render_generated_transaction(&mut self, row: &ImportTransaction) -> Result<String>

Render a generated reconciliation row without counting it as a source transaction. Its count is reported separately in the preview (#462, DESIGN §48).

ImportStreamRenderer::validate_generated_file

pub fn validate_generated_file(
        &self,
        name: &str,
        text: &str,
        mut check: impl FnMut() -> Result<()>,
    ) -> Result<()>

Check one completed Markdown file before a caller writes it to a private staging sink. One month is parsed at a time to bound memory (#462, DESIGN §48).

ImportStreamRenderer::finish

pub fn finish(
        self,
        mut files: BTreeMap<String, String>,
        months: &[String],
        checks: Vec<ImportCheckSummary>,
        ready_to_assign_adjustment_count: usize,
        mut check: impl FnMut() -> Result<()>,
    ) -> Result<ImportPlan>

Finalize streamed month files and derive the aggregate import preview. Month documents are checked one at a time, so the verification does not need a full parsed Ledger beside all generated rows (#462, DESIGN §48).

ImportStreamRenderer::finish_staged

pub fn finish_staged(
        self,
        months: &[String],
        checks: Vec<ImportCheckSummary>,
        ready_to_assign_adjustment_count: usize,
        mut check: impl FnMut() -> Result<()>,
    ) -> Result<ImportPlan>

Finish a streamed import whose complete files have already been checked and written by the caller. The returned plan contains only summary data, not every month document (#462, DESIGN §48).

Source: crates/calternal-money/src/import.rs:405

ImportSummary

pub struct ImportSummary

Aggregate import counts, a bounded source-row sample, and codec result.

Fields

• pub account_count: usize: Number of imported Accounts.
• pub category_count: usize: Number of imported and generated Categories.
• pub assignment_count: usize: Number of monthly assignments.
• pub transaction_count: usize: Number of source transaction rows, including generated opening balances; source Ready to Assign reconciliation rows have a separate count because they do not represent source transactions.
• pub ready_to_assign_adjustment_count: usize: Number of generated source Ready to Assign reconciliation rows.
• pub split_count: usize: Number of split rows.
• pub transfer_count: usize: Number of transfer rows.
• pub cleared_count: usize: Number of rows marked cleared.
• pub month_count: usize: Number of generated month files.
• pub preview_rows: Vec<ImportPreviewRow>: The first source rows only, for a concrete but bounded preview.
• pub byte_stable_round_trip: bool: True only when every generated file reads and serializes byte-for-byte.
• pub checks: Vec<ImportCheckSummary>: Aggregate differential check counts shown in the preview.
• pub mismatch_classes: Vec<String>: Check classes with at least one mismatch. No row details are included.

Implements: Clone, Debug, Serialize

Source: crates/calternal-money/src/import.rs:271

ImportTransaction

pub struct ImportTransaction

One source transaction after paired transfers and split rows are grouped.

Fields

• pub notes: String: Separate source notes; never folded into the Payee (#1130).
• pub reconciled: bool: Source reconciliation state, independent of cleared (#1130).
• pub source_rows: Vec<SourceRow>: Original rows, including split children and both transfer legs (#1130).
• pub source_id: String: Stable transaction identity in the source export.
• pub date: String: Calendar date YYYY-MM-DD.
• pub amount: Minor: Exact amount in currency minor units.
• pub currency: String: Currency used by the transaction amount.
• pub account_source_id: String: Source account identity.
• pub category_source_id: Option<String>: Source Category ID for a simple transaction, if present.
• pub preview_payee: Option<String>: Source Payee without its separate memo, for the bounded preview sample.
• pub payee: String: Payee text. Actual notes use the separate notes field (#1130).
• pub cleared: bool: Source cleared mark, independent of reconciliation for Actual (#1130).
• pub splits: Vec<ImportSplit>: Split children, in source file order.
• pub transfer: Option<ImportTransfer>: Transfer destination, if this row moves money between accounts.
• pub transfer_category_source_id: Option<String>: Source Category posted by an on-budget-to-off-budget transfer.
• pub fx: Option<(Minor, String)>: Confirmed source amount for foreign-currency rows.
• pub fx_total: Option<(Minor, String)>: Exact amount in the Budget currency for foreign-currency rows.
• pub is_opening_balance: bool: True when this row is the source’s opening-balance transaction.
• pub ready_to_assign_adjustment: Option<Minor>: A source-engine Ready to Assign change attached to a zero-value row.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:109

ImportTransfer

pub struct ImportTransfer

One destination account leg in a source transfer.

Fields

• pub account_source_id: String: Source account identity for the destination.
• pub amount: Minor: Exact destination amount in currency minor units.
• pub currency: String: Currency used by the destination amount.

Implements: Clone, Debug

Source: crates/calternal-money/src/import.rs:98

ImportVerification

pub struct ImportVerification

Exact source totals that the Money projection must reproduce.

Fields

• pub account_balances: Vec<ImportAccountBalance>: Month-end account balances from the source transactions or API.
• pub category_months: Vec<ImportCategoryMonth>: Monthly Category budgeted, activity and closing balance values.
• pub ready_to_assign: Vec<ImportReadyToAssign>: Monthly Ready to Assign values provided or computed from source tables.

Implements: Clone, Debug, Default

Source: crates/calternal-money/src/import.rs:214

SourceRow

pub struct SourceRow

Lossless evidence for split children, transfer legs and Tracking categories whose posting uses a system Category (#1130). Amounts are minor units. The writer maps Account and Category IDs to stable Money anchors; these rows never post a second time or alter any balance.

Fields

• pub id: String: Immutable source identity.
• pub date: String: Calendar date, without time-zone conversion.
• pub amount: i64: Exact minor units.
• pub account_id: String: Account identity, mapped to a Money anchor on write.
• pub category_id: Option<String>: Category identity, when the source supplied one.
• pub payee: String: Payee without notes.
• pub notes: String: Notes, including whitespace and line breaks.
• pub cleared: bool: Source cleared mark, independent of reconciliation.
• pub reconciled: bool: Source reconciled mark.

Implements: Clone, Debug, Eq, PartialEq, Serialize, Deserialize

Source: crates/calternal-money/src/import.rs:155

Traits

ImportFileSink

pub trait ImportFileSink: Send

Store one complete generated file while a large Actual import is streamed. Names come from the Money writer, and implementations must use rooted storage rather than deriving paths from source values (#462, DESIGN §48).

ImportFileSink::write_file

fn write_file(&mut self, name: &str, content: &str) -> Result<()>;

Store exact Markdown bytes under one generated Money file name.

Source: crates/calternal-money/src/import.rs:372