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 record builders for merging N same-item tracked entities into ONE new
// entity — the deliberate lot merge behind batch-completion outputs ("2 lots of
// the same item — merge into one?"). The inverse shape of buildBatchSplitRecords
// in ./batch-split.ts: parents become Consumed, a fresh entity carries the
// summed quantity, one Merge activity records inputs = each parent at its
// quantity and output = the merged entity, and the ledger gets net-zero Batch
// Merge rows (−q at each parent's bin, +Σq at the merged entity's bin).
// The merged quantity rounds once, at this persist boundary.
// See .ai/specs/2026-09-16-batch-materials-and-output-lots.md.
import { round } from "@carbon/database/precision";
export type BatchMergeParent = {
id: string;
readableId: string | null;
quantity: number;
/** the parent's on-ledger balance (Σ itemLedger.quantity). A lot straight
* off a completed batch has 0 until its job is received — the merge is an
* identity operation and must only move stock that actually exists. */
receivedQuantity: number;
status: string;
sourceDocument: string | null;
sourceDocumentId: string | null;
sourceDocumentReadableId: string | null;
itemId: string | null;
expirationDate: string | null;
attributes: Record<string, unknown> | null;
/** the parent's resolved bin — its −q ledger row books here */
bin: { storageUnitId: string | null; locationId: string | null };
};
type MergeLedgerRecord = {
postingDate: string;
itemId: string | null;
quantity: number;
locationId: string | null;
storageUnitId: string | null;
entryType: "Negative Adjmt." | "Positive Adjmt.";
documentType: "Batch Merge";
documentId: string;
trackedEntityId: string;
createdBy: string;
companyId: string;
};
type MergeActivityEdgeRecord = {
trackedActivityId: string;
trackedEntityId: string;
quantity: number;
companyId: string;
createdBy: string;
};
// Pointer keys from the split convention never carry onto a merged entity —
// its provenance is the Merge activity plus "Merged From Entity IDs".
const POINTER_KEYS = ["Split Entity ID", "Split From Entity ID"];
export function buildBatchMergeRecords(input: {
parents: BatchMergeParent[];
/** caller-supplied nanoid for the merged entity */
mergedId: string;
/** caller-supplied nanoid for the Merge activity */
mergeActivityId: string;
/** the merged lot's batch number. Omitted/null inherits the FIRST parent's,
* matching buildBatchSplitRecords (a split child keeps parent.readableId).
* An Available lot with no number is unidentifiable on the floor. */
readableId?: string | null;
activitySourceDocument?: string;
activitySourceDocumentId?: string;
companyId: string;
userId: string;
/** yyyy-MM-dd */
postingDate: string;
}): {
mergedEntityInsert: {
id: string;
readableId: string | null;
sourceDocument: string | null;
sourceDocumentId: string | null;
sourceDocumentReadableId: string | null;
quantity: number;
status: "Available";
attributes: Record<string, unknown>;
itemId: string | null;
expirationDate: string | null;
companyId: string;
createdBy: string;
};
/** parents keep their quantity (historical record, like any consumption) and flip Consumed */
parentUpdates: { id: string; status: "Consumed" }[];
activityInsert: {
id: string;
type: "Merge";
sourceDocument?: string;
sourceDocumentId?: string;
attributes: Record<string, unknown>;
companyId: string;
createdBy: string;
};
activityInputInserts: MergeActivityEdgeRecord[];
activityOutputInsert: MergeActivityEdgeRecord;
ledgerInserts: MergeLedgerRecord[];
} {
const {
parents,
mergedId,
mergeActivityId,
readableId,
activitySourceDocument,
activitySourceDocumentId,
companyId,
userId,
postingDate
} = input;
if (parents.length < 2) {
throw new Error("At least two lots are required to merge");
}
for (const parent of parents) {
if (parent.status !== "Available") {
throw new Error(
`Lot ${parent.readableId ?? parent.id} is not available to merge`
);
}
if (!(parent.quantity > 0)) {
throw new Error(
`Lot ${parent.readableId ?? parent.id} has no quantity to merge`
);
}
if (parent.receivedQuantity < 0) {
throw new Error(
`Lot ${parent.readableId ?? parent.id} has a negative ledger balance`
);
}
}
const itemOf = (p: BatchMergeParent) => p.itemId ?? p.sourceDocumentId;
const firstItem = itemOf(parents[0]!);
if (!firstItem || parents.some((p) => itemOf(p) !== firstItem)) {
throw new Error("Only lots of the same item can be merged");
}
// Sum first, round once — the three-boundary rule. Summing N raw quantities
// then rounding the total keeps the merged lot a clean 5dp value even when
// the parents carry float residue (0.1 + 0.2 → 0.3, not 0.30000000000000004).
const totalQuantity = round(parents.reduce((sum, p) => sum + p.quantity, 0));
// Earliest parent expiry wins — the conservative policy for a blended lot.
let expirationDate: string | null = null;
for (const p of parents) {
if (
p.expirationDate &&
(!expirationDate || p.expirationDate < expirationDate)
) {
expirationDate = p.expirationDate;
}
}
// Keep only the attributes every parent agrees on; anything contested is
// dropped rather than guessed.
const first = parents[0]!;
const agreed: Record<string, unknown> = {};
for (const [key, value] of Object.entries(
(first.attributes ?? {}) as Record<string, unknown>
)) {
if (POINTER_KEYS.includes(key)) continue;
const everyoneAgrees = parents.every(
(p) =>
JSON.stringify(
((p.attributes ?? {}) as Record<string, unknown>)[key]
) === JSON.stringify(value)
);
if (everyoneAgrees) agreed[key] = value;
}
return {
mergedEntityInsert: {
id: mergedId,
readableId: readableId ?? first.readableId,
sourceDocument: first.sourceDocument,
sourceDocumentId: first.sourceDocumentId,
sourceDocumentReadableId: first.sourceDocumentReadableId,
quantity: totalQuantity,
status: "Available",
attributes: {
...agreed,
"Merged From Entity IDs": parents.map((p) => p.id)
},
itemId: first.itemId,
expirationDate,
companyId,
createdBy: userId
},
parentUpdates: parents.map((p) => ({ id: p.id, status: "Consumed" })),
activityInsert: {
id: mergeActivityId,
type: "Merge",
...(activitySourceDocument
? { sourceDocument: activitySourceDocument }
: {}),
...(activitySourceDocumentId
? { sourceDocumentId: activitySourceDocumentId }
: {}),
attributes: {
"Merged Quantity": totalQuantity,
"Merged From Entity IDs": parents.map((p) => p.id),
"Merged Entity ID": mergedId
},
companyId,
createdBy: userId
},
activityInputInserts: parents.map((p) => ({
trackedActivityId: mergeActivityId,
trackedEntityId: p.id,
quantity: p.quantity,
companyId,
createdBy: userId
})),
activityOutputInsert: {
trackedActivityId: mergeActivityId,
trackedEntityId: mergedId,
quantity: totalQuantity,
companyId,
createdBy: userId
},
// Ledger rows move only stock the parents actually had: each job's
// receipt is still what brings its quantity into inventory (and lands on
// the merged lot once the parent is consumed). A parent received in full
// makes these net to zero, which is the old behaviour.
ledgerInserts: [
...parents
.filter((p) => p.receivedQuantity > 0)
.map(
(p): MergeLedgerRecord => ({
postingDate,
itemId: p.itemId ?? p.sourceDocumentId,
quantity: -round(p.receivedQuantity),
locationId: p.bin.locationId,
storageUnitId: p.bin.storageUnitId,
entryType: "Negative Adjmt.",
documentType: "Batch Merge",
documentId: mergeActivityId,
trackedEntityId: p.id,
createdBy: userId,
companyId
})
),
// One positive row per bin the parents occupied: the merge changes
// which lot the stock belongs to, never where it is.
...receivedByBin(parents).map(
({ bin, quantity }): MergeLedgerRecord => ({
postingDate,
itemId: first.itemId ?? first.sourceDocumentId,
quantity,
locationId: bin.locationId,
storageUnitId: bin.storageUnitId,
entryType: "Positive Adjmt.",
documentType: "Batch Merge",
documentId: mergeActivityId,
trackedEntityId: mergedId,
createdBy: userId,
companyId
})
)
]
};
}
// Received quantity summed per bin, in the order the bins first appear.
function receivedByBin(parents: BatchMergeParent[]) {
const byBin = new Map<
string,
{ bin: BatchMergeParent["bin"]; quantity: number }
>();
for (const p of parents) {
if (p.receivedQuantity <= 0) continue;
const key = `${p.bin.locationId}|${p.bin.storageUnitId}`;
const entry = byBin.get(key) ?? { bin: p.bin, quantity: 0 };
// Round PER PARENT, the same way the negative rows above do — a bin total
// rounded only at the end can differ from the sum of the per-parent
// negatives by a minor unit, and the Batch Merge pair stops netting to
// zero. Each parent's received quantity is its own persist boundary.
entry.quantity += round(p.receivedQuantity);
byBin.set(key, entry);
}
// Round the accumulated total too: summing already-rounded parts is exact in
// decimal but not in binary float (0.1 + 0.2).
return [...byBin.values()].map((entry) => ({
bin: entry.bin,
quantity: round(entry.quantity)
}));
}