Skip to content

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.

18.7 KB
Raw Blame
// 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.

// The pure decisions of the accounting cutover
// (.ai/specs/implemented/2026-10-08-accounting-cutover.md sections 4 and 5): the opening
// journal, Migration Clearing per control account, the inventory reset and
// the re-costing of outbound movements after the cutover date. No database
// reads or writes here — the enable transaction feeds these and writes what
// they return.

import { parseDate } from "@internationalized/date";
import {
  type CostingMethod,
  type ReliefEvent,
  type ReliefLayer,
  replayReliefs
} from "./cost-relief";
import { type AccountClass, debitSigned } from "./ledger";
import { assertBalanced, EPSILON, equals, round } from "./precision";
import type { Database } from "./types";

/** The document type a journal line carries. */
export type JournalLineDocumentType =
  Database["public"]["Enums"]["journalLineDocumentType"];

export type { AccountClass } from "./ledger";

/** Migration Clearing must total zero within this for the enable. */
export const MIGRATION_CLEARING_TOLERANCE = 0.01;

/** True when Migration Clearing totals zero within the tolerance. */
export function isMigrationClearingZero(total: number): boolean {
  return equals(total, 0, MIGRATION_CLEARING_TOLERANCE);
}

/** The search param the enable wizard carries the cutover date in. */
export const ACTIVATION_CUTOVER_PARAM = "cutover";

/** The day before the cutover: the date the opening journal carries. */
export function dayBeforeCutover(cutoverDate: string): string {
  return parseDate(cutoverDate).subtract({ days: 1 }).toString();
}

/**
 * The class the Migration Clearing account must have. Readiness refuses any
 * other, and the opening journal refuses to be built on one.
 */
export const MIGRATION_CLEARING_ACCOUNT_CLASS: AccountClass = "Equity";

/** The Migration Clearing account default, with its class. */
export type MigrationClearingAccount = {
  accountId: string;
  accountClass: AccountClass;
};

export type OpenItemType =
  | "Receivable"
  | "Payable"
  | "Reimbursement"
  | "Unapplied Credit"
  | "Customer Deposit"
  | "Received Not Invoiced"
  | "Invoiced Not Received"
  | "Work in Progress"
  | "Inventory"
  | "Fixed Asset Cost"
  | "Accumulated Depreciation"
  | "Deferred Revenue"
  | "Lease Net Investment"
  | "Lease Liability"
  | "Right-of-Use Asset"
  | "Accumulated ROU Amortization";

/**
 * One item open at the cutover, in base currency, positive on the natural
 * side of its account. `amount` is `originalAmount − settledBeforeCutover`.
 * A document partly settled before the cutover keeps its original amount
 * because the payment lookup and the AR/AP readers subtract every settlement
 * from the original control line, the settlements before the cutover
 * included. An item that is not a document has `settledBeforeCutover = 0`.
 */
export type OpenItem = {
  openItemType: OpenItemType;
  accountId: string;
  accountClass: AccountClass;
  amount: number;
  originalAmount: number;
  settledBeforeCutover: number;
  documentType: JournalLineDocumentType | null;
  documentId: string | null;
  documentLineReference: string | null;
  description: string;
  /**
   * What the wizard shows for the item: the document's readable number and
   * its customer or supplier. Never written to the opening journal.
   */
  reference?: string | null;
  partyName?: string | null;
  /** The original line's quantity, for a reader that costs by quantity. */
  quantity?: number | null;
  /**
   * The original line is an accrual (`journalLine.accrual`). Invoiced-not-
   * received uses it: a receipt after the cutover costs the units invoiced
   * before it from the accrual lines of `purchase-invoice:<poLineId>`.
   */
  accrual?: boolean;
  /**
   * How the part settled before the cutover is keyed. Without it, that line
   * keeps the item's keys under "<description> (settled before cutover)".
   * Received-not-invoiced uses it: the invoices before the cutover cleared
   * GR/IR under `purchase-invoice:<poLineId>`, which the purchase invoice's
   * GR/IR walk does not read.
   */
  settled?: {
    documentLineReference: string | null;
    description: string;
    quantity?: number | null;
  } | null;
};

/** A line of the prior system's trial balance as of the day before the cutover. */
export type TrialBalanceLine = {
  accountId: string;
  accountClass: AccountClass;
  debit: number;
  credit: number;
};

export type OpeningJournalLine = {
  accountId: string;
  /** Natural-balance-signed, as every journal line in Carbon. */
  amount: number;
  description: string;
  documentType: JournalLineDocumentType | null;
  documentId: string | null;
  documentLineReference: string | null;
  quantity: number | null;
  /** Present, and true, on an open item's accrual line only. */
  accrual?: true;
};

export const SETTLED_BEFORE_CUTOVER_SUFFIX = " (settled before cutover)";
export const MIGRATION_CLEARING_DESCRIPTION = "Migration Clearing";
export const OPENING_BALANCE_DESCRIPTION = "Opening Balance";

function netDebit(line: TrialBalanceLine) {
  return line.debit - line.credit;
}

/**
 * The opening journal's lines:
 * - per open item, its original amount with its own description, document
 *   keys and accrual flag, and, when part was settled before the cutover,
 *   that part with the opposite sign under a description the readers ignore;
 * - one Migration Clearing line per control account offsetting its items;
 * - per trial balance row on a non-control account, a line on that account
 *   and a Migration Clearing line offsetting it.
 * A trial balance row on a control account is an assertion only (it feeds
 * `migrationClearingByAccount`), never a line.
 *
 * Migration Clearing must be an Equity account; the lines are signed by its
 * class, and the function refuses lines that do not balance.
 */
export function buildOpeningJournalLines(
  items: OpenItem[],
  trialBalance: TrialBalanceLine[],
  controlAccountIds: ReadonlySet<string>,
  clearing: MigrationClearingAccount
): OpeningJournalLine[] {
  if (clearing.accountClass !== MIGRATION_CLEARING_ACCOUNT_CLASS) {
    throw new Error(
      `Migration Clearing must be an ${MIGRATION_CLEARING_ACCOUNT_CLASS} account, not ${clearing.accountClass}`
    );
  }

  const lines: OpeningJournalLine[] = [];
  const classByAccount = new Map<string, AccountClass>([
    [clearing.accountId, clearing.accountClass]
  ]);
  const debitByControlAccount = new Map<string, number>();

  for (const item of items) {
    if (!controlAccountIds.has(item.accountId)) {
      throw new Error(
        `Open item on ${item.accountId} is not on a control account`
      );
    }
    classByAccount.set(item.accountId, item.accountClass);
    const keys = {
      documentType: item.documentType,
      documentId: item.documentId,
      documentLineReference: item.documentLineReference
    };
    lines.push({
      accountId: item.accountId,
      amount: round(item.originalAmount),
      description: item.description,
      ...keys,
      quantity: item.quantity ?? null,
      ...(item.accrual ? { accrual: true as const } : {})
    });
    if (Math.abs(item.settledBeforeCutover) > EPSILON) {
      lines.push({
        accountId: item.accountId,
        amount: round(-item.settledBeforeCutover),
        ...(item.settled
          ? {
              ...keys,
              description: item.settled.description,
              documentLineReference: item.settled.documentLineReference,
              quantity: item.settled.quantity ?? null
            }
          : {
              ...keys,
              description: `${item.description}${SETTLED_BEFORE_CUTOVER_SUFFIX}`,
              quantity: null
            })
      });
    }
    debitByControlAccount.set(
      item.accountId,
      (debitByControlAccount.get(item.accountId) ?? 0) +
        debitSigned(item.accountClass, item.amount)
    );
  }

  for (const [accountId, debitValue] of debitByControlAccount) {
    if (Math.abs(debitValue) <= EPSILON) continue;
    lines.push({
      accountId: clearing.accountId,
      amount: round(debitSigned(clearing.accountClass, -debitValue)),
      description: MIGRATION_CLEARING_DESCRIPTION,
      documentType: null,
      documentId: null,
      documentLineReference: accountId,
      quantity: null
    });
  }

  for (const row of trialBalance) {
    if (controlAccountIds.has(row.accountId)) continue;
    const debitValue = netDebit(row);
    if (Math.abs(debitValue) <= EPSILON) continue;
    classByAccount.set(row.accountId, row.accountClass);
    lines.push({
      accountId: row.accountId,
      amount: round(debitSigned(row.accountClass, debitValue)),
      description: OPENING_BALANCE_DESCRIPTION,
      documentType: null,
      documentId: null,
      documentLineReference: null,
      quantity: null
    });
    lines.push({
      accountId: clearing.accountId,
      amount: round(debitSigned(clearing.accountClass, -debitValue)),
      description: MIGRATION_CLEARING_DESCRIPTION,
      documentType: null,
      documentId: null,
      documentLineReference: row.accountId,
      quantity: null
    });
  }

  let debits = 0;
  let credits = 0;
  for (const line of lines) {
    const accountClass = classByAccount.get(line.accountId);
    if (!accountClass) {
      throw new Error(`Opening journal line on ${line.accountId} has no class`);
    }
    const debitValue = debitSigned(accountClass, line.amount);
    if (debitValue > 0) debits += debitValue;
    else credits -= debitValue;
  }
  assertBalanced(debits, credits, EPSILON, "Opening journal");

  return lines;
}

export type MigrationClearingRow = {
  accountId: string;
  /** Debit-signed balance the prior system's trial balance asserts. */
  trialBalance: number;
  /** Debit-signed balance of Carbon's open items on the account. */
  carbon: number;
  difference: number;
};

/**
 * Migration Clearing per control account, and its total. The total is the
 * debit-signed balance Migration Clearing ends at after the opening journal:
 * the sum of the control-account differences plus any imbalance of the trial
 * balance itself. The enable needs it to be zero.
 */
export function migrationClearingByAccount(
  items: OpenItem[],
  trialBalance: TrialBalanceLine[],
  controlAccountIds: ReadonlySet<string>
): { rows: MigrationClearingRow[]; total: number } {
  const carbon = new Map<string, number>();
  for (const item of items) {
    carbon.set(
      item.accountId,
      (carbon.get(item.accountId) ?? 0) +
        debitSigned(item.accountClass, item.amount)
    );
  }
  const asserted = new Map<string, number>();
  let nonControlDebit = 0;
  for (const row of trialBalance) {
    if (controlAccountIds.has(row.accountId)) {
      asserted.set(
        row.accountId,
        (asserted.get(row.accountId) ?? 0) + netDebit(row)
      );
    } else {
      nonControlDebit += netDebit(row);
    }
  }

  const rows = [...controlAccountIds].map((accountId) => {
    const trialBalanceAmount = round(asserted.get(accountId) ?? 0);
    const carbonAmount = round(carbon.get(accountId) ?? 0);
    return {
      accountId,
      trialBalance: trialBalanceAmount,
      carbon: carbonAmount,
      difference: round(trialBalanceAmount - carbonAmount)
    };
  });

  const itemsDebit = [...carbon.values()].reduce((sum, v) => sum + v, 0);
  // The clearing lines offset every item and every non-control trial balance
  // row, so the clearing account ends at minus their debit total.
  const total = round(-(itemsDebit + nonControlDebit));
  return { rows, total: total === 0 ? 0 : total };
}

/**
 * An open item the user may ignore on Migration Clearing: a sales or purchase
 * invoice. Before the cutover another system kept the books, so an invoice
 * open in Carbon may already be settled there. The enable marks an ignored
 * invoice Paid as of the day before the cutover, which every receivables and
 * payables reader already treats as closed. Any other item has no such state:
 * leaving it out of the opening journal would misstate what reads it later.
 *
 * Not an invoice Carbon itself settles on or after the cutover
 * (`settledFromCutoverIds`): that payment's journal credits the control
 * account, which with no opening line would leave it short by the payment.
 */
export function isIgnorableOpenItem(
  item: OpenItem,
  settledFromCutoverIds: ReadonlySet<string>
): boolean {
  return (
    (item.openItemType === "Receivable" || item.openItemType === "Payable") &&
    item.documentType === "Invoice" &&
    item.documentId !== null &&
    !settledFromCutoverIds.has(item.documentId)
  );
}

/**
 * The trial balance with every control account set to Carbon's opening total
 * for it, debit-signed as `migrationClearingByAccount` reports it, and every
 * other row kept. Each control account's difference becomes zero. What is
 * left — the Migration Clearing total — is the amount the trial balance is
 * now out of balance by; it goes to `balancingAccountId` (retained
 * earnings), added to any row already there, so Migration Clearing totals
 * zero and the plug is a trial balance line the user can see and change.
 */
export function applyCarbonToTrialBalance(
  trialBalance: TrialBalanceLine[],
  rows: MigrationClearingRow[],
  controlAccountIds: ReadonlySet<string>,
  balancingAccountId: string
): { accountId: string; debit: number; credit: number }[] {
  if (controlAccountIds.has(balancingAccountId)) {
    throw new Error("The balancing account cannot be a control account");
  }
  const debitByAccount = new Map<string, number>();
  const add = (accountId: string, value: number) =>
    debitByAccount.set(accountId, (debitByAccount.get(accountId) ?? 0) + value);
  for (const line of trialBalance) {
    if (!controlAccountIds.has(line.accountId)) {
      add(line.accountId, netDebit(line));
    }
  }
  for (const row of rows) add(row.accountId, row.carbon);
  const outOfBalance = [...debitByAccount.values()].reduce(
    (sum, value) => sum + value,
    0
  );
  add(balancingAccountId, -outOfBalance);

  return [...debitByAccount].flatMap(([accountId, value]) => {
    const amount = round(value);
    if (Math.abs(amount) <= EPSILON) return [];
    return [
      {
        accountId,
        debit: amount > 0 ? amount : 0,
        credit: amount < 0 ? -amount : 0
      }
    ];
  });
}

/** The layer that opens an item's stock at the cutover. */
export type OpeningLayer = {
  itemId: string;
  quantity: number;
  cost: number;
};

/**
 * The inventory reset as of the cutover date: one opening layer per item with
 * stock, at the reviewed unit cost. The caller closes every layer dated
 * before the cutover. Cost layers have no location, so on-hand is per item.
 */
export function planInventoryReset(
  onHandAtCutover: { itemId: string; quantity: number }[],
  unitCostByItem: ReadonlyMap<string, number>
): OpeningLayer[] {
  return onHandAtCutover.flatMap(({ itemId, quantity }) => {
    if (quantity <= EPSILON) return [];
    const unitCost = unitCostByItem.get(itemId);
    if (unitCost === undefined) {
      throw new Error(
        `Item ${itemId} has stock at the cutover but no unit cost`
      );
    }
    return [
      { itemId, quantity: round(quantity), cost: round(quantity * unitCost) }
    ];
  });
}

/** A cost layer dated before the cutover, with its cost adjustments included. */
export type LayerBeforeCutover = { quantity: number; cost: number };

/**
 * The value of an item's stock at the cutover, replayed from its layers
 * dated before the cutover (oldest first). Relief before the cutover took
 * the oldest layers for FIFO and the newest for LIFO, so the stock left sits
 * in the newest layers for FIFO and the oldest for LIFO. Today's remaining
 * quantity cannot answer this: relief after the cutover has changed it.
 * A quantity no layer covers is valued at `fallbackUnitCost`.
 */
export function unitCostAtCutover(
  layers: LayerBeforeCutover[],
  onHandAtCutover: number,
  costingMethod: "FIFO" | "LIFO",
  fallbackUnitCost: number
): number {
  if (onHandAtCutover <= EPSILON) return fallbackUnitCost;
  const ordered = costingMethod === "FIFO" ? [...layers].reverse() : layers;
  let toCover = onHandAtCutover;
  let value = 0;
  for (const layer of ordered) {
    if (toCover <= EPSILON) break;
    if (layer.quantity <= EPSILON) continue;
    const take = Math.min(toCover, layer.quantity);
    value += (take * layer.cost) / layer.quantity;
    toCover -= take;
  }
  if (toCover > EPSILON) value += toCover * fallbackUnitCost;
  return round(value / onHandAtCutover);
}

/** A layer the re-cost opens: the opening layer or an inbound layer after
 *  the cutover, at its full quantity, with its adjustment children. */
export type RecostLayer = ReliefLayer & { itemId: string };

/** An outbound movement after the cutover; quantity and cost are positive. */
export type RecostOutbound = {
  costLedgerId: string;
  itemId: string;
  quantity: number;
  cost: number;
  /** The serial units leaving with it. */
  trackedEntityIds: readonly string[];
};

/** The re-cost's ledger, in order: the opening layers first, then every
 *  inbound layer and outbound movement after the cutover as it was posted. */
export type RecostEvent = { layer: RecostLayer } | { outbound: RecostOutbound };

/**
 * Re-costs the outbound movements dated on or after the cutover against the
 * reset layers: the events run in order, each outbound movement relieving the
 * layers open at that point as `calculateCOGS` relieves them
 * (`replayReliefs`). Only FIFO and LIFO items relieve layers; the caller
 * passes those only, as Standard and Average cost from `itemCost`. Returns
 * each movement's new cost and its difference from the stored one, and the
 * remaining quantity of every layer and child.
 */
export function recostOutbound(
  events: readonly RecostEvent[],
  methodByItem: ReadonlyMap<string, CostingMethod>,
  fallbackUnitCostByItem: ReadonlyMap<string, number>
): {
  movements: { costLedgerId: string; newCost: number; delta: number }[];
  remainingById: Map<string, number>;
} {
  const outbound = events.flatMap((event) =>
    "outbound" in event ? [event.outbound] : []
  );
  const { costByKey, remainingById } = replayReliefs({
    events: events.map(
      (event): ReliefEvent =>
        "layer" in event
          ? { kind: "layer", itemId: event.layer.itemId, layer: event.layer }
          : {
              kind: "relief",
              key: event.outbound.costLedgerId,
              itemId: event.outbound.itemId,
              quantity: event.outbound.quantity,
              trackedEntityIds: event.outbound.trackedEntityIds
            }
    ),
    methodByItem,
    fallbackUnitCostByItem
  });
  return {
    movements: outbound.map((movement) => {
      const newCost = costByKey.get(movement.costLedgerId) ?? 0;
      return {
        costLedgerId: movement.costLedgerId,
        newCost,
        delta: round(newCost - movement.cost)
      };
    }),
    remainingById
  };
}