@atcn/subledger 1.3.0

package/dist/projection.js

@@ -0,0 +1,218 @@
+import { digestOf } from "@atcn/schema";
+import { computeRollup, costSign } from "./rollup.js";
+import { CLOSURE_DOCUMENT_TYPE, RECEIPT_DOCUMENT_TYPE, SUBLEDGER_SCHEMA_VERSION, } from "./documents.js";
+import { ATTESTABLE_FIELDS } from "./types.js";
+/** Claims superseded by a later correction stay visible and gain the "superseded" label. */
+export function labelClaims(claims) {
+    const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
+    return claims.map((c) => (superseded.has(c.event_id) && !c.assurance.includes("superseded") ? { ...c, assurance: [...c.assurance, "superseded"] } : c));
+}
+const STATUS_BY_CLAIM = {
+    acceptance: "accepted",
+    completion: "completed",
+    partial_completion: "partially_completed",
+    cancellation: "cancelled",
+    provider_failure: "provider_failed",
+};
+/** Delivery status is the latest non-superseded status claim. It is a recorded claim, not an adjudicated truth. */
+export function deliveryStatus(claims) {
+    const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
+    const active = claims.filter((c) => STATUS_BY_CLAIM[c.type] && !superseded.has(c.event_id));
+    const latest = active.at(-1);
+    return latest ? STATUS_BY_CLAIM[latest.type] : "delegated";
+}
+/** Totals for a single delegation's own events (no allocation detail, which may name other cost centers). */
+export function receiptTotals(delegation, events) {
+    const rollup = computeRollup({
+        root: { task_id: "receipt_scope", currency: delegation.currency, budget_minor: null },
+        delegations: [{ ...delegation, parent_delegation_id: null }],
+        events,
+        attribution: Object.fromEntries(events.map((e) => [e.financial_event_id, delegation.delegation_id])),
+        allocations: {},
+    });
+    const direct = rollup.nodes.find((n) => n.node_id === delegation.delegation_id).direct;
+    const result = {};
+    for (const [currency, { allocated: _allocated, unallocated: _unallocated, ...rest }] of Object.entries(direct))
+        result[currency] = rest;
+    return result;
+}
+function openCorrectionFields(responses) {
+    const fields = new Set();
+    for (const r of responses) {
+        if (r.statement.response_type !== "propose_correction")
+            continue;
+        if (r.decision?.status === "accepted")
+            continue;
+        for (const c of r.statement.corrections)
+            fields.add(c.field);
+    }
+    return fields;
+}
+export function receiptFieldStatus(delegation, claims, events, priorResponses) {
+    const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
+    const active = claims.filter((c) => !superseded.has(c.event_id) && c.type !== "correction");
+    const stateOf = (claim) => {
+        if (!claim)
+            return "missing";
+        if (claim.asserted_by === "provider")
+            return "provider_reported";
+        if (claim.asserted_by === "buyer")
+            return "buyer_asserted";
+        return "imported";
+    };
+    const status = {
+        "delivery.status": stateOf(active.filter((c) => STATUS_BY_CLAIM[c.type]).at(-1)),
+        "delivery.evidence": stateOf(active.filter((c) => c.evidence.length > 0).at(-1)),
+        "scope.terms_digest": delegation.terms_digest ? "buyer_asserted" : "missing",
+        "financial.amounts": events.some((e) => costSign(e.type) !== 0 || e.type === "quote") ? "imported" : "missing",
+        "financial.status": events.some((e) => e.normalized_status !== "unknown") ? "imported" : "missing",
+    };
+    for (const field of openCorrectionFields(priorResponses))
+        status[field] = "contested";
+    return status;
+}
+/**
+ * Provider receipt: one delegation only. Omits sibling delegations, root customer/project/cost-center data,
+ * allocation lines, liability and economic-event IDs, and private event hashes (acceptance 8, 19).
+ */
+export function buildReceiptPayload(input) {
+    const d = input.delegation;
+    const claims = labelClaims(input.claims);
+    const fieldStatus = receiptFieldStatus(d, claims, input.events, input.prior_responses);
+    return {
+        document_type: RECEIPT_DOCUMENT_TYPE,
+        schema_version: SUBLEDGER_SCHEMA_VERSION,
+        receipt_id: input.receipt_id,
+        revision: input.revision,
+        previous_receipt_id: input.previous?.receipt_id ?? null,
+        previous_receipt_digest: input.previous?.digest ?? null,
+        issued_at: input.issued_at,
+        expires_at: input.expires_at,
+        issuer: input.issuer,
+        delegation: {
+            delegation_id: d.delegation_id,
+            root_task_id: d.root_task_id,
+            external_ref: d.external_ref,
+            provider_job_ref: d.provider_job_ref,
+            shared_description: d.shared_description,
+            terms_digest: d.terms_digest,
+            currency: d.currency,
+            quoted_max_minor: d.quoted_max_minor,
+            quote_basis: d.quote_basis,
+            accepted_amount_minor: d.accepted_amount_minor,
+            expected_delivery: d.expected_delivery,
+            retrospective: d.retrospective,
+            downstream_visibility: d.downstream_visibility,
+        },
+        provider: {
+            provider_id: input.provider?.provider_id ?? null,
+            name_stated: input.provider?.name ?? d.provider_name_stated,
+            provider_own_id: input.provider?.provider_own_id ?? d.provider_own_id,
+            identity_binding: input.provider_key_bound ? "key_bound" : "not_bound",
+        },
+        delivery_claims: claims.map(({ delegation_id: _delegationId, ...claim }) => claim),
+        financial_events: input.events.map(({ liability_owner: _liabilityOwner, economic_event_id: _economicEventId, fx: _fx, ...event }) => ({
+            ...event,
+            allocation_version: input.allocation_versions[event.financial_event_id] ?? 0,
+        })),
+        totals: receiptTotals(d, input.events),
+        field_status: fieldStatus,
+        unverified_fields: ATTESTABLE_FIELDS.filter((f) => fieldStatus[f] !== "missing"),
+        corrections: input.prior_responses
+            .filter((r) => r.statement.response_type === "propose_correction")
+            .map((r) => ({ response_id: r.response_id, receipt_revision: r.receipt_revision, fields: r.statement.fields, decision: r.decision?.status ?? "open" })),
+        lineage: { complete: input.capture_gaps.length === 0, capture_gaps: input.capture_gaps.map(({ delegation_id: _delegationId, ...gap }) => gap) },
+    };
+}
+/** Latest allocation lines per financial event, the input the roll-up uses. */
+export function latestAllocations(allocations) {
+    const latest = {};
+    for (const a of allocations)
+        if (!latest[a.financial_event_id] || latest[a.financial_event_id].version < a.version)
+            latest[a.financial_event_id] = a;
+    return latest;
+}
+export function rollupFor(task, delegations, events, allocations) {
+    const latest = latestAllocations(allocations);
+    return computeRollup({
+        root: { task_id: task.task_id, currency: task.currency, budget_minor: task.budget_minor },
+        delegations,
+        events: events.map((e) => e.record),
+        attribution: Object.fromEntries(events.map((e) => [e.record.financial_event_id, e.attributed_to])),
+        allocations: Object.fromEntries(Object.entries(latest).map(([id, a]) => [id, a.lines])),
+    });
+}
+export function closureDisclosure(input) {
+    const missing = [];
+    const unverified = [];
+    const contested = [];
+    const providerReported = [];
+    const retrospective = [];
+    if (input.task.retrospective)
+        retrospective.push(`task:${input.task.task_id}`);
+    for (const d of input.delegations) {
+        if (!d.provider_id)
+            missing.push(`delegation:${d.delegation_id}.provider`);
+        if (!d.terms_digest)
+            missing.push(`delegation:${d.delegation_id}.terms_digest`);
+        if (!input.claims.some((c) => c.delegation_id === d.delegation_id && STATUS_BY_CLAIM[c.type]))
+            missing.push(`delegation:${d.delegation_id}.delivery_status`);
+        if (d.downstream_visibility === "unknown")
+            missing.push(`delegation:${d.delegation_id}.downstream_work`);
+        if (d.retrospective)
+            retrospective.push(`delegation:${d.delegation_id}`);
+    }
+    for (const c of input.claims) {
+        if (c.evidence.length === 0)
+            unverified.push(`delivery_claim:${c.event_id}.evidence`);
+        if (c.asserted_by === "provider")
+            providerReported.push(`delivery_claim:${c.event_id}`);
+        if (c.retrospective)
+            retrospective.push(`delivery_claim:${c.event_id}`);
+    }
+    for (const { record } of input.events) {
+        if (!record.evidence)
+            unverified.push(`financial_event:${record.financial_event_id}.evidence`);
+        if (record.retrospective)
+            retrospective.push(`financial_event:${record.financial_event_id}`);
+    }
+    for (const r of input.responses) {
+        if (r.statement.response_type === "submit_evidence")
+            providerReported.push(`response:${r.response_id}`);
+        if (r.statement.response_type === "propose_correction" && r.decision?.status !== "accepted") {
+            for (const c of r.statement.corrections)
+                contested.push(`receipt:${r.receipt_id}.${c.field}`);
+        }
+    }
+    return { missing, unverified, contested, provider_reported: providerReported, retrospective };
+}
+/** Private closure snapshot of the full root task: lineage, event digests, all allocation versions, roll-up, and open exceptions. */
+export function buildClosurePayload(input) {
+    return {
+        document_type: CLOSURE_DOCUMENT_TYPE,
+        schema_version: SUBLEDGER_SCHEMA_VERSION,
+        closure_id: input.closure_id,
+        version: input.version,
+        previous_closure_id: input.previous?.closure_id ?? null,
+        previous_closure_digest: input.previous?.digest ?? null,
+        generated_at: input.generated_at,
+        issuer: input.issuer,
+        task: input.task,
+        delegations: input.delegations,
+        delivery_claims: labelClaims(input.claims),
+        financial_events: input.events.map((e) => ({ record: e.record, event_digest: digestOf(e.record), attributed_to: e.attributed_to })),
+        allocations: input.allocations,
+        rollup: rollupFor(input.task, input.delegations, input.events, input.allocations),
+        open_exceptions: input.open_exceptions,
+        receipts: input.receipts,
+        responses: input.responses,
+        key_bindings: input.key_bindings,
+        lineage: {
+            complete: input.capture_gaps.length === 0,
+            capture_gaps: input.capture_gaps,
+            unknown_downstream: input.delegations.filter((d) => d.downstream_visibility === "unknown").map((d) => d.delegation_id),
+        },
+        disclosure: closureDisclosure(input),
+        ...(input.obligation_links && input.obligation_links.length > 0 ? { obligation_links: input.obligation_links } : {}),
+    };
+}

package/dist/response.d.ts

@@ -0,0 +1,24 @@
+import { type Correction, type ResponseStatement } from "./documents.js";
+import type { AttestableField, EvidenceRef, ResponseType } from "./types.js";
+export interface StatementInput {
+    receipt: {
+        receipt_id: string;
+        digest: string;
+        revision: number;
+        issuer_operator_id: string;
+    };
+    response_type: ResponseType;
+    fields: AttestableField[];
+    note?: string | null;
+    evidence?: EvidenceRef[];
+    corrections?: Correction[];
+}
+/** Builds the statement a provider responds with. Field order is irrelevant: the signature covers canonical JSON. */
+export declare function buildResponseStatement(input: StatementInput): ResponseStatement;
+export declare function statementDigest(statement: ResponseStatement): string;
+/** Provider-side signing (in the browser page, SDK, or provider tooling). The service never sees the private key. */
+export declare function signStatement(statement: ResponseStatement, privateKey: string): string;
+/** Operator-side countersignature over a closure or receipt payload, made with a key the operator holds. */
+export declare function countersignPayload(payload: unknown, privateKey: string): string;
+export declare function verifyCountersignature(payload: unknown, signature: string, publicKey: string): boolean;
+export declare function verifyStatementSignature(statement: ResponseStatement, signature: string, publicKey: string): boolean;

package/dist/response.js

@@ -0,0 +1,34 @@
+import { canonicalize, digestOf, signBytes, utf8Encode, verifyBytes } from "@atcn/schema";
+import { RESPONSE_STATEMENT_TYPE } from "./documents.js";
+/** Builds the statement a provider responds with. Field order is irrelevant: the signature covers canonical JSON. */
+export function buildResponseStatement(input) {
+    return {
+        document_type: RESPONSE_STATEMENT_TYPE,
+        receipt_id: input.receipt.receipt_id,
+        receipt_digest: input.receipt.digest,
+        receipt_revision: input.receipt.revision,
+        issuer_operator_id: input.receipt.issuer_operator_id,
+        response_type: input.response_type,
+        fields: [...new Set(input.fields)].sort(),
+        note: input.note ?? null,
+        evidence: input.evidence ?? [],
+        corrections: input.corrections ?? [],
+    };
+}
+export function statementDigest(statement) {
+    return digestOf(statement);
+}
+/** Provider-side signing (in the browser page, SDK, or provider tooling). The service never sees the private key. */
+export function signStatement(statement, privateKey) {
+    return signBytes(utf8Encode(canonicalize(statement)), privateKey);
+}
+/** Operator-side countersignature over a closure or receipt payload, made with a key the operator holds. */
+export function countersignPayload(payload, privateKey) {
+    return signBytes(utf8Encode(canonicalize(payload)), privateKey);
+}
+export function verifyCountersignature(payload, signature, publicKey) {
+    return verifyBytes(utf8Encode(canonicalize(payload)), signature, publicKey);
+}
+export function verifyStatementSignature(statement, signature, publicKey) {
+    return verifyBytes(utf8Encode(canonicalize(statement)), signature, publicKey);
+}

package/dist/rollup.d.ts

@@ -0,0 +1,78 @@
+import type { AllocationLine, DelegationNode, FinancialEventRecord, FinancialEventType, RootNode } from "./types.js";
+/** Per-currency figures for one node. Amounts are never combined across currencies. */
+export interface Totals {
+    quoted: number;
+    accepted: number;
+    invoiced: number;
+    charged: number;
+    fees: number;
+    adjustments: number;
+    refunded: number;
+    credits: number;
+    reported_paid: number;
+    /** Buyer expense: invoiced + charged + fees + adjustments - refunded - credits. */
+    net_cost: number;
+    /** Billed but not reported paid: invoiced + charged + fees + adjustments - credits - reported_paid. Refunds cancel out of both sides. */
+    unresolved: number;
+    /** Cost reported for downstream work that the buyer does not pay directly (included in a parent fee, or paid by another party). */
+    downstream_reported: number;
+    allocated: number;
+    unallocated: number;
+}
+export type CurrencyTotals = Record<string, Totals>;
+export interface NodeRollup {
+    node_id: string;
+    parent_id: string | null;
+    direct: CurrencyTotals;
+    descendant: CurrencyTotals;
+    total: CurrencyTotals;
+    event_ids: string[];
+}
+export interface RollupInput {
+    root: RootNode;
+    delegations: DelegationNode[];
+    events: FinancialEventRecord[];
+    /** Current attribution: financial_event_id -> node id (task id or delegation id). */
+    attribution: Record<string, string>;
+    /** Current allocation lines per financial_event_id. */
+    allocations: Record<string, AllocationLine[]>;
+}
+export interface Rollup {
+    root_task_id: string;
+    nodes: NodeRollup[];
+    root_total: CurrencyTotals;
+    excluded_event_ids: {
+        reversed: string[];
+        reversals: string[];
+        fx_rates: string[];
+    };
+}
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+export declare function costSign(type: FinancialEventType): 1 | -1 | 0;
+export declare function emptyTotals(): Totals;
+/** True when an event counts as the buyer's own expense rather than reported downstream cost (acceptance 25). */
+export declare function isBuyerExpense(event: FinancialEventRecord): boolean;
+/**
+ * Deterministic roll-up of one root task (acceptance 1, 6, 25). Each event is attributed to exactly one node
+ * and counted once; parents show direct and descendant cost separately. Reversed events and the reversals
+ * themselves are excluded from all totals but stay in the record.
+ */
+export declare function computeRollup(input: RollupInput): Rollup;
+export interface Conversion {
+    report_currency: string;
+    converted_net_cost: number | null;
+    rates_used: {
+        currency: string;
+        fx_event_id: string;
+        rate_numerator: number;
+        rate_denominator: number;
+        as_of: string;
+    }[];
+    missing_rates: string[];
+    rounding: "half_up_per_currency";
+}
+/**
+ * Converts per-currency net cost into one report currency only with explicit, dated fx_rate events (acceptance 5).
+ * Uses the latest rate dated on or before asOf for each currency; any missing rate leaves the total null.
+ */
+export declare function convertNetCost(totals: CurrencyTotals, reportCurrency: string, fxEvents: FinancialEventRecord[], asOf: string): Conversion;

package/dist/rollup.js

@@ -0,0 +1,176 @@
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+export function costSign(type) {
+    if (type === "invoice" || type === "charge" || type === "fee" || type === "adjustment")
+        return 1;
+    if (type === "refund" || type === "credit")
+        return -1;
+    return 0;
+}
+export function emptyTotals() {
+    return {
+        quoted: 0,
+        accepted: 0,
+        invoiced: 0,
+        charged: 0,
+        fees: 0,
+        adjustments: 0,
+        refunded: 0,
+        credits: 0,
+        reported_paid: 0,
+        net_cost: 0,
+        unresolved: 0,
+        downstream_reported: 0,
+        allocated: 0,
+        unallocated: 0,
+    };
+}
+function bucket(totals, currency) {
+    totals[currency] ??= emptyTotals();
+    return totals[currency];
+}
+function addInto(target, source) {
+    for (const [currency, values] of Object.entries(source)) {
+        const into = bucket(target, currency);
+        for (const key of Object.keys(values))
+            into[key] += values[key];
+    }
+}
+/** True when an event counts as the buyer's own expense rather than reported downstream cost (acceptance 25). */
+export function isBuyerExpense(event) {
+    return event.payer === "buyer" && event.included_in_event_id === null;
+}
+/**
+ * Deterministic roll-up of one root task (acceptance 1, 6, 25). Each event is attributed to exactly one node
+ * and counted once; parents show direct and descendant cost separately. Reversed events and the reversals
+ * themselves are excluded from all totals but stay in the record.
+ */
+export function computeRollup(input) {
+    const reversed = new Set(input.events.filter((e) => e.type === "reversal" && e.reverses_event_id).map((e) => e.reverses_event_id));
+    const nodeIds = [input.root.task_id, ...input.delegations.map((d) => d.delegation_id)];
+    const nodes = new Map();
+    nodes.set(input.root.task_id, { node_id: input.root.task_id, parent_id: null, direct: {}, descendant: {}, total: {}, event_ids: [] });
+    for (const d of input.delegations) {
+        nodes.set(d.delegation_id, { node_id: d.delegation_id, parent_id: d.parent_delegation_id ?? input.root.task_id, direct: {}, descendant: {}, total: {}, event_ids: [] });
+    }
+    const latestQuote = new Map();
+    for (const event of input.events) {
+        const nodeId = input.attribution[event.financial_event_id];
+        if (!nodeId || !nodes.has(nodeId))
+            continue;
+        if (event.type === "fx_rate" || event.type === "reversal")
+            continue;
+        if (reversed.has(event.financial_event_id))
+            continue;
+        const node = nodes.get(nodeId);
+        node.event_ids.push(event.financial_event_id);
+        const t = bucket(node.direct, event.currency);
+        if (event.type === "quote") {
+            const previous = latestQuote.get(nodeId);
+            if (!previous || previous.event_date < event.event_date || (previous.event_date === event.event_date && previous.financial_event_id < event.financial_event_id)) {
+                latestQuote.set(nodeId, event);
+            }
+            continue;
+        }
+        if (event.type === "payment_reported") {
+            t.reported_paid += event.amount_minor;
+            continue;
+        }
+        const sign = costSign(event.type);
+        if (!isBuyerExpense(event)) {
+            t.downstream_reported += sign * event.amount_minor;
+            continue;
+        }
+        if (event.type === "invoice")
+            t.invoiced += event.amount_minor;
+        if (event.type === "charge")
+            t.charged += event.amount_minor;
+        if (event.type === "fee")
+            t.fees += event.amount_minor;
+        if (event.type === "adjustment")
+            t.adjustments += event.amount_minor;
+        if (event.type === "refund")
+            t.refunded += event.amount_minor;
+        if (event.type === "credit")
+            t.credits += event.amount_minor;
+        const lines = input.allocations[event.financial_event_id] ?? [];
+        const allocated = lines.filter((l) => l.target.type !== "unallocated").reduce((sum, l) => sum + l.amount_minor, 0);
+        t.allocated += sign * Math.sign(event.amount_minor || 1) * allocated;
+    }
+    for (const d of input.delegations) {
+        const node = nodes.get(d.delegation_id);
+        const quote = latestQuote.get(d.delegation_id);
+        if (quote)
+            bucket(node.direct, quote.currency).quoted += quote.amount_minor;
+        else if (d.quoted_max_minor !== null)
+            bucket(node.direct, d.currency).quoted += d.quoted_max_minor;
+        if (d.accepted_amount_minor !== null)
+            bucket(node.direct, d.currency).accepted += d.accepted_amount_minor;
+    }
+    const rootQuote = latestQuote.get(input.root.task_id);
+    if (rootQuote)
+        bucket(nodes.get(input.root.task_id).direct, rootQuote.currency).quoted += rootQuote.amount_minor;
+    for (const node of nodes.values()) {
+        for (const t of Object.values(node.direct)) {
+            t.net_cost = t.invoiced + t.charged + t.fees + t.adjustments - t.refunded - t.credits;
+            t.unresolved = t.invoiced + t.charged + t.fees + t.adjustments - t.credits - t.reported_paid;
+            t.unallocated = t.net_cost - t.allocated;
+        }
+    }
+    // Children before parents: deepest first, so each subtree total is final when added to its parent.
+    const depth = (id) => {
+        let d = 0;
+        let current = nodes.get(id);
+        while (current.parent_id) {
+            d += 1;
+            current = nodes.get(current.parent_id);
+        }
+        return d;
+    };
+    const order = [...nodeIds].sort((a, b) => depth(b) - depth(a));
+    for (const id of order) {
+        const node = nodes.get(id);
+        addInto(node.total, node.direct);
+        addInto(node.total, node.descendant);
+        if (node.parent_id)
+            addInto(nodes.get(node.parent_id).descendant, node.total);
+    }
+    return {
+        root_task_id: input.root.task_id,
+        nodes: nodeIds.map((id) => nodes.get(id)),
+        root_total: nodes.get(input.root.task_id).total,
+        excluded_event_ids: {
+            reversed: [...reversed].sort(),
+            reversals: input.events.filter((e) => e.type === "reversal").map((e) => e.financial_event_id).sort(),
+            fx_rates: input.events.filter((e) => e.type === "fx_rate").map((e) => e.financial_event_id).sort(),
+        },
+    };
+}
+/**
+ * Converts per-currency net cost into one report currency only with explicit, dated fx_rate events (acceptance 5).
+ * Uses the latest rate dated on or before asOf for each currency; any missing rate leaves the total null.
+ */
+export function convertNetCost(totals, reportCurrency, fxEvents, asOf) {
+    const rates_used = [];
+    const missing_rates = [];
+    let sum = 0n;
+    for (const [currency, t] of Object.entries(totals).sort(([a], [b]) => a.localeCompare(b))) {
+        if (currency === reportCurrency) {
+            sum += BigInt(t.net_cost);
+            continue;
+        }
+        const candidates = fxEvents
+            .filter((e) => e.type === "fx_rate" && e.fx && e.fx.base_currency === currency && e.fx.quote_currency === reportCurrency && e.event_date <= asOf)
+            .sort((a, b) => (a.event_date === b.event_date ? a.financial_event_id.localeCompare(b.financial_event_id) : a.event_date.localeCompare(b.event_date)));
+        const rate = candidates.at(-1);
+        if (!rate) {
+            missing_rates.push(currency);
+            continue;
+        }
+        const numerator = BigInt(t.net_cost) * BigInt(rate.fx.rate_numerator);
+        const denominator = BigInt(rate.fx.rate_denominator);
+        const half = denominator / 2n;
+        sum += numerator >= 0n ? (numerator + half) / denominator : -((-numerator + half) / denominator);
+        rates_used.push({ currency, fx_event_id: rate.financial_event_id, rate_numerator: rate.fx.rate_numerator, rate_denominator: rate.fx.rate_denominator, as_of: rate.event_date });
+    }
+    return { report_currency: reportCurrency, converted_net_cost: missing_rates.length ? null : Number(sum), rates_used, missing_rates, rounding: "half_up_per_currency" };
+}