Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
// Pure construction of the GL journal for posting a credit/debit memo. No DB, no
// I/O, no clock — so it is unit-testable. The driver
// (`post-memo-transaction.ts`) resolves the control + reason account ids, the
// reason account's class, the accounting period and `journalLineReference` (all
// impure), then hands them here to compute the balanced double-entry.
//
// A memo is payment-shaped, NOT invoice-shaped: it moves an amount between the
// party's AR/AP control account and a single chosen reason account. There are
// four combos (customer/supplier × credit/debit); two axes drive the posting:
// * isAR — customer (AR, asset control) vs supplier (AP, liability control)
// * direction — 'Credit' or 'Debit'. This alone decides the control side:
// a Debit memo DEBITS the control account, a Credit memo CREDITS
// it — for BOTH AR and AP. Worked through:
// Customer Credit → reduce AR → CR asset (control credit)
// Customer Debit → increase AR→ DR asset (control debit)
// Supplier Credit → increase AP→ CR liab. (control credit)
// Supplier Debit → reduce AP → DR liab. (control debit)
// i.e. controlIsDebit === (direction === 'Debit') universally.
// The reason leg is always the inverse side, booked at the reason account's
// natural class so its stored natural-balance `amount` sign is correct.
//
// A memo is a single-currency document booked at its own exchange rate, so there
// is no realized FX at post time (FX only realizes when CASH later settles the
// memo — a separate payment posting).
//
// Both legs normally use the same base amount, so the entry balances on two
// lines. SUPPLIER RETURNS are the one exception: the return shipment already
// debited GRNI at the goods' CARRIED COST, so the memo must credit GRNI by that
// same carried cost to clear it, while AP moves by what the supplier actually
// agreed to credit. Those two figures are independent, and the difference is a
// purchase price variance — emitted as a third leg. Without it the credit and
// the cost never reconcile and GRNI keeps a permanent residual.
import { toBaseAmount } from "./accounting-currency.ts";
import { accountTypeFromClass, credit, debit } from "./ledger.ts";
import { assertBalanced, round } from "./precision.ts";
type AccountType = "asset" | "liability" | "equity" | "revenue" | "expense";
// A journal line this builder emits. Self-contained — a pure unit shouldn't
// depend on the generated DB types, and `journalLine.documentType`'s "Memo" enum
// value (migration 20260628143012) isn't in the generated lib/types.ts until the
// DB is rebuilt. The driver spreads `journalId` on before the Kysely insert.
export interface MemoJournalLine {
accountId: string;
description: string;
amount: number;
quantity: number;
documentType: "Memo";
documentId: string;
journalLineReference: string;
companyId: string;
}
export interface BuildMemoJournalInput {
// Internal memo record id — becomes `documentId` on every line.
memoId: string;
companyId: string;
// customer (AR) vs supplier (AP). Drives control account TYPE (asset/liability).
isAR: boolean;
direction: "Credit" | "Debit";
// Memo principal in document currency and its foreign-per-base snapshot.
amount: number;
exchangeRate: number;
// Resolved once by the driver (nanoid) so this stays pure.
journalLineReference: string;
// receivables (AR) / payables (AP) control account.
controlAccountId: string;
// the memo's chosen reason account + its glAccountClass.
reasonAccountId: string;
reasonAccountClass: string;
// Supplier-return memos only. The reason leg (GRNI) must clear the EXACT
// amount the return shipment debited — the carried cost of the goods, in
// BASE currency — not the amount the supplier agreed to credit. When the two
// differ, the difference is a purchase price variance and needs its own leg,
// or the suspense account never nets to zero. Omit both for every other memo
// and the entry stays the ordinary two-line shape.
reasonAmountBase?: number;
varianceAccountId?: string | null;
// Overrides the reason leg's description. Defaults to "Credit memo" /
// "Debit memo"; a supplier return names the account instead ("Goods
// Received Not Invoiced") so the three-line entry reads the same way the
// return shipment's own GRNI line does.
reasonDescription?: string;
}
export interface BuildMemoJournalResult {
lines: MemoJournalLine[];
// Running debit(+)/credit(−) balance; ~0 for a balanced entry.
signedDebitTotal: number;
}
// Maximum residual (base ccy) we tolerate before refusing to post.
const BALANCE_TOLERANCE = 0.01;
export function buildMemoJournal(
input: BuildMemoJournalInput
): BuildMemoJournalResult {
const {
memoId,
companyId,
isAR,
direction,
amount,
exchangeRate,
journalLineReference,
controlAccountId,
reasonAccountId,
reasonAccountClass,
reasonAmountBase,
varianceAccountId,
reasonDescription
} = input;
if (!controlAccountId) {
throw new Error(
`Missing ${
isAR ? "receivables" : "payables"
} account default; cannot post memo to GL`
);
}
if (!Number.isFinite(amount) || amount <= 0) {
throw new Error("Memo amount must be greater than 0 to post");
}
const magnitude = toBaseAmount(amount, exchangeRate);
const lines: MemoJournalLine[] = [];
let signedDebitTotal = 0;
const pushLine = (
side: "debit" | "credit",
accountType: AccountType,
accountId: string,
description: string,
// Defaults to the memo magnitude; only the reason and variance legs of a
// supplier return pass their own.
lineMagnitude: number = magnitude
) => {
signedDebitTotal += side === "debit" ? lineMagnitude : -lineMagnitude;
lines.push({
accountId,
description,
amount:
side === "debit"
? debit(accountType, lineMagnitude)
: credit(accountType, lineMagnitude),
quantity: 1,
documentType: "Memo",
documentId: memoId,
journalLineReference,
companyId
});
};
// Control side is decided by direction alone (see header note).
const controlIsDebit = direction === "Debit";
const controlType: AccountType = isAR ? "asset" : "liability";
const reasonType = accountTypeFromClass(reasonAccountClass);
// 1) Control leg (AR/AP).
pushLine(
controlIsDebit ? "debit" : "credit",
controlType,
controlAccountId,
isAR ? "Accounts Receivable" : "Accounts Payable"
);
// 2) Reason leg — always the inverse side of the control leg.
//
// Normally it carries the same magnitude, so the entry balances on two
// lines. A supplier return is the exception: the reason account (GRNI)
// must be cleared at the CARRIED COST the return shipment debited, while
// the control leg (AP) moves by what the supplier actually credited. When
// those differ, the reason leg uses its own magnitude and the remainder
// becomes leg 3.
const reasonMagnitude =
reasonAmountBase === undefined
? magnitude
: round(Math.abs(reasonAmountBase));
pushLine(
controlIsDebit ? "credit" : "debit",
reasonType,
reasonAccountId,
reasonDescription ??
(direction === "Credit" ? "Credit memo" : "Debit memo"),
reasonMagnitude
);
// 3) Variance leg — the plug that makes an unequal control/reason pair
// balance. Same economic family as the invoice-vs-receipt PPV
// (`post-purchase-invoice`), so it shares `purchaseVarianceAccount` and is
// told apart by its own description.
const varianceMagnitude = round(Math.abs(signedDebitTotal));
if (varianceMagnitude > 0.005) {
if (!varianceAccountId) {
throw new Error(
"Memo reason amount differs from the memo amount but no variance account was provided; cannot post an unbalanced memo"
);
}
// signedDebitTotal > 0 means debits currently exceed credits, so the plug
// must be a credit (a gain: credited more than the goods were carried at).
pushLine(
signedDebitTotal > 0 ? "credit" : "debit",
"expense",
varianceAccountId,
"Purchase Price Variance",
varianceMagnitude
);
}
// BALANCE_TOLERANCE is a business threshold (multi-currency memos carry
// sub-cent cross-rate residuals), NOT the float-noise default.
assertBalanced(
signedDebitTotal,
0,
BALANCE_TOLERANCE,
"Memo journal (base currency)"
);
return { lines, signedDebitTotal };
}