| name | multi-currency-translation |
| description | Translate/remeasure ONE entity's functional-currency trial balance into a presentation-currency (USD) TB before consolidate.py, via scripts/remeasure.py. Current-rate method (A&L @ closing, P&L @ average, equity @ historical; plug = CTA to OCI/equity) or temporal method (monetary @ closing, non-monetary @ historical, P&L @ average except REV_EXP_HIST @ historical; plug = remeasurement G/L to net income). Reuses statement_engine's section-signed presentation + reasoning trail — no new sign logic. Blocks on a missing/invalid rate_class, blocks when the balancing plug fails the analytical CTA self-check, and refuses a highly_inflationary + current_rate combo (ASC 830 vs IAS 29). Decision-support, not an audited remeasurement. Used by `controller`. |
Skill: multi-currency-translation
Purpose: consolidate.py flags a non-functional-currency entity and emits an honest CTA note, but treats its trial balance as if already stated in the group presentation currency. This skill removes that simplification: remeasure.py translates one entity's functional-currency trial balance into a presentation-currency (USD) trial balance that then feeds consolidate.py's worksheet — before its SystemExit 6 "consolidated balance sheet == 0.00" assertion, which stays the guardrail.
Engine: ../../scripts/remeasure.py (stdlib only, Python 3.8+). It imports statement_engine.py: the translated debits/credits are pure arithmetic (functional amount × the rate its rate_class maps to), but the presentation sign of every line is statement_engine._present's section-based convention reused verbatim, and the subtotals + reasoning trail come from statement_engine.build_income_statement / build_balance_sheet. No new accounting-sign logic.
The two methods
| CURRENT-RATE (translation) | TEMPORAL (remeasurement) |
|---|
| Assets & liabilities | all @ closing | monetary @ closing, non-monetary @ historical |
| Income / expense | all @ average | @ average EXCEPT non-monetary-linked (COGS / depreciation / prepaid amort — REV_EXP_HIST) @ historical |
| Equity | @ historical | @ historical |
| Balancing plug | CTA — a component of OCI / equity; does not touch net income | remeasurement gain/(loss) — flows through net income |
| When | functional currency ≠ reporting currency (local currency is functional) | reporting currency is the functional currency (or a highly inflationary economy) |
The rate_class column (COA mapping)
The per-entity COA mapping gains one column: rate_class ∈ {MONETARY, NONMONETARY, EQUITY_CONTRIB, EQUITY_RE, REV_EXP, REV_EXP_HIST}. A blank or invalid value BLOCKS the run (rc3) exactly like an unmapped account — the same statement_engine.lint_mapping discipline — and the engine also blocks if a rate_class disagrees with the account's statement/section (e.g. MONETARY on an equity line). See examples/coa-mapping-fx.csv.
The rates.json
{
"method": "current_rate",
"closing": 1.1,
"average": 1.05,
"historical": { "default": 1.0, "1200": 1.02 },
"highly_inflationary": false
}
historical is an object: a default plus optional per-account overrides (keyed by account id). An optional dividends: {"amount": <functional>, "declaration_rate": <rate>} feeds the analytical CTA self-check (defaults to zero). See examples/rates-current.json and examples/rates-temporal.json.
The CTA self-check (blocks a wrong plug)
The balance-sheet-balancing plug is not trusted on faith. For the current-rate method the engine computes the analytical CTA —
begin_net_assets × (closing − historical)
+ NI × (closing − average)
− dividends × (closing − declaration)
— and BLOCKS (rc5) unless it equals the balancing plug within 0.01. A plug that doesn't reconcile to the theory is a bug, not a CTA.
Hyperinflation refusal (ASC 830 vs IAS 29)
A highly_inflationary: true + method: "current_rate" combination is REFUSED (rc7). Under ASC 830 a highly inflationary economy's books are remeasured as if the reporting currency were the functional currency (use method: "temporal"), never translated at the current rate. IAS 29 (restate-for-inflation-then-translate at closing) is a different framework and is out of scope — flag it for a human preparer.
Zero-drift no-op
When the entity's functional currency equals the presentation currency there is nothing to translate: the engine short-circuits and the emitted presentation TB (--out-tb) is a byte-identical copy of the source, so the consolidate.py path for an all-USD group is unchanged. Verified in ../../scripts/test_remeasure.py.
Invocation
python3 scripts/remeasure.py \
--entity skills/multi-currency-translation/examples/eur-sub.json \
--coa skills/multi-currency-translation/examples/coa-mapping-fx.csv \
--tb skills/multi-currency-translation/examples/tb-eur-sub-2026-06.csv \
--rates skills/multi-currency-translation/examples/rates-temporal.json \
--presentation-currency USD \
--out-tb eur-sub-usd.csv \
--out eur-sub-translation.json
Then point the consolidate.py config's entity tb at the emitted USD trial balance. The engine blocks on: an invalid entity profile (rc2), a functional TB that is out of balance (rc4), a missing/invalid rate_class (rc3), a failed CTA self-check (rc5), and refuses a hyperinflation + current-rate combo (rc7).
Correctness discipline
- The golden fixtures
examples/expected-remeasured-current.json and examples/expected-remeasured-temporal.json are hand-derived by independent arithmetic from the EUR trial balance (each carries its _derivation), NOT frozen from a remeasure.py run.
- The acceptance suite
../../scripts/test_remeasure.py asserts the load-bearing claims: current-rate golden (CTA = 200, NI = 1050), temporal golden (remeasurement loss = −80, NI = 970), the CTA self-check blocks on a wrong plug, a blank/invalid rate_class blocks, the hyperinflation combo is refused, the all-USD case is a byte-identical no-op, and the emitted TB is balanced (so consolidate.py's rc6 guardrail is never tripped by construction).
What this is not
Not an audited translation, a GAAP/IFRS determination, or a live-rate-verified remeasurement. Sourcing the closing/average/historical rates, the IdP / warehouse wiring, and any real credentials are the consumer's step. Non-controlling interests, intra-period rate movements, translation of accumulated OCI, and IAS 29 restatement are out of scope for this slice — flag them for a human preparer. Outputs are decision-support (see ../../CLAUDE.md §3, §4 "currency mixing without explicit FX rate disclosure", §12 "GAAP/IFRS vs. management view").
