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 the batch split/merge convention, shared by the
// server functions and the ERP (quality-disposition). Quantities round at THIS
// persist boundary, so every caller inherits it.
//
// Convention (spec .ai/specs/2026-08-04-batch-split-identity-flip.md): on a
// partial draw of quantity q from a parent batch, the PARENT KEEPS its id and
// is decremented; a NEW child entity departs with q, tagged
// "Split From Entity ID": parent.id. The Split activity records input
// parent@q → output child@q (never a survivor self-loop), and the ledger gets
// exactly two net-zero Batch Split rows (−q parent, +q child) at the parent's
// resolved bin. Returns MERGE quantity back into the parent (Merge activity).
import { equals, round } from "@carbon/database/precision";
/**
* The ONE split gate: is this draw the entity's whole quantity?
*
* Every caller decides "split or take the whole entity" with this, so the gate
* and `buildBatchSplitRecords`' own `draw < parentQty` guard can never
* disagree. A raw `===`/`<` on two float quantities can: a residue draw (an
* entity left holding 0.020000000000000018 after an earlier split, drawn for
* 0.02) reads as a PARTIAL draw, and the builder then throws `draw >= parentQty`
* on what the operator sees as a legitimate full pick — or mints a phantom
* child holding 1.8e-17. Both sides round to internal scale first, so two 5dp
* quantities that differ by real stock (one minor unit, 1e-5) still split.
*/
export function isFullDraw(
entityQuantity: number,
drawQuantity: number
): boolean {
return equals(round(entityQuantity), round(drawQuantity));
}
export type BatchSplitInput = {
parent: {
id: string;
readableId: string | null;
quantity: number;
sourceDocument: string | null;
sourceDocumentId: string | null;
sourceDocumentReadableId: string | null;
itemId: string | null;
expirationDate: string | null;
attributes: Record<string, unknown> | null;
};
/** q — must be > 0 and < parent.quantity (full draws never split) */
drawQuantity: number;
/** caller-supplied nanoid for the departing child entity */
childId: string;
/** caller-supplied nanoid for the Split activity */
splitActivityId: string;
/** e.g. "Picking List" */
activitySourceDocument: string;
activitySourceDocumentId: string;
/** the parent's resolved bin — both ledger rows book here */
bin: { storageUnitId: string | null; locationId: string | null };
/** itemId for the ledger rows */
itemLedgerItemId: string | null;
companyId: string;
userId: string;
/** yyyy-MM-dd */
postingDate: string;
childStatus: "Available" | "Consumed" | "Scrapped";
extraChildAttributes?: Record<string, unknown>;
};
type LedgerRecord = {
postingDate: string;
itemId: string | null;
quantity: number;
locationId: string | null;
storageUnitId: string | null;
entryType: "Negative Adjmt." | "Positive Adjmt.";
documentType: "Batch Split";
documentId: string;
trackedEntityId: string;
createdBy: string;
companyId: string;
};
type ActivityEdgeRecord = {
trackedActivityId: string;
trackedEntityId: string;
quantity: number;
companyId: string;
createdBy: string;
};
export function buildBatchSplitRecords(input: BatchSplitInput): {
childEntityInsert: {
id: string;
readableId: string | null;
sourceDocument: string | null;
sourceDocumentId: string | null;
sourceDocumentReadableId: string | null;
quantity: number;
status: "Available" | "Consumed" | "Scrapped";
attributes: Record<string, unknown>;
itemId: string | null;
expirationDate: string | null;
companyId: string;
createdBy: string;
};
parentUpdate: { quantity: number };
activityInsert: {
id: string;
type: "Split";
sourceDocument: string;
sourceDocumentId: string;
attributes: Record<string, unknown>;
companyId: string;
createdBy: string;
};
activityInputInsert: ActivityEdgeRecord;
activityOutputInsert: ActivityEdgeRecord;
ledgerInserts: [LedgerRecord, LedgerRecord];
} {
const {
parent,
drawQuantity,
childId,
splitActivityId,
activitySourceDocument,
activitySourceDocumentId,
bin,
itemLedgerItemId,
companyId,
userId,
postingDate,
childStatus,
extraChildAttributes
} = input;
// Round at the persist boundary so a float-residue draw (0.98 from 1.0 leaves
// 0.020000000000000018, not 0.02) never reaches storage. The child departs
// with `draw`, the parent keeps `remaining`, and both ledger rows book `draw`
// — all derived from the same rounded values so the two stay net-zero.
const draw = round(drawQuantity);
const parentQty = round(parent.quantity);
const remaining = round(parentQty - draw);
// The callers' split gates (full draws take the no-split fast path, compared
// with equals() at scale) should make these unreachable — loud beats silent.
if (draw <= 0) {
throw new Error(
`buildBatchSplitRecords: drawQuantity must be > 0, got ${drawQuantity}`
);
}
if (draw >= parentQty) {
throw new Error(
`buildBatchSplitRecords: drawQuantity (${drawQuantity}) must be < parent quantity (${parent.quantity}) — a full draw is not a split`
);
}
// Clone the parent's attributes minus any stale pointer keys; the child
// carries the one true back-pointer to its parent.
const {
"Split Entity ID": _staleForwardPointer,
"Split From Entity ID": _staleBackPointer,
...inheritedAttributes
} = (parent.attributes ?? {}) as Record<string, unknown>;
return {
childEntityInsert: {
id: childId,
readableId: parent.readableId,
sourceDocument: parent.sourceDocument,
sourceDocumentId: parent.sourceDocumentId,
sourceDocumentReadableId: parent.sourceDocumentReadableId,
quantity: draw,
status: childStatus,
attributes: {
...inheritedAttributes,
"Split From Entity ID": parent.id,
...extraChildAttributes
},
itemId: parent.itemId,
expirationDate: parent.expirationDate,
companyId,
createdBy: userId
},
parentUpdate: { quantity: remaining },
activityInsert: {
id: splitActivityId,
type: "Split",
sourceDocument: activitySourceDocument,
sourceDocumentId: activitySourceDocumentId,
attributes: {
"Original Quantity": parentQty,
"Drawn Quantity": draw,
"Remaining Quantity": remaining,
"Split Entity ID": childId
},
companyId,
createdBy: userId
},
activityInputInsert: {
trackedActivityId: splitActivityId,
trackedEntityId: parent.id,
quantity: draw,
companyId,
createdBy: userId
},
activityOutputInsert: {
trackedActivityId: splitActivityId,
trackedEntityId: childId,
quantity: draw,
companyId,
createdBy: userId
},
ledgerInserts: [
{
postingDate,
itemId: itemLedgerItemId,
quantity: -draw,
locationId: bin.locationId,
storageUnitId: bin.storageUnitId,
entryType: "Negative Adjmt.",
documentType: "Batch Split",
documentId: splitActivityId,
trackedEntityId: parent.id,
createdBy: userId,
companyId
},
{
postingDate,
itemId: itemLedgerItemId,
quantity: draw,
locationId: bin.locationId,
storageUnitId: bin.storageUnitId,
entryType: "Positive Adjmt.",
documentType: "Batch Split",
documentId: splitActivityId,
trackedEntityId: childId,
createdBy: userId,
companyId
}
]
};
}
export function buildMergeRecords(input: {
child: { id: string; quantity: number };
parent: { id: string; quantity: number };
mergeQuantity: number;
mergeActivityId: string;
companyId: string;
userId: string;
}): {
activityInsert: {
id: string;
type: "Merge";
attributes: Record<string, unknown>;
companyId: string;
createdBy: string;
};
activityInputInsert: ActivityEdgeRecord;
activityOutputInsert: ActivityEdgeRecord;
parentUpdate: { quantity: number };
childUpdate: { quantity: number; status?: "Consumed" };
} {
const { child, parent, mergeQuantity, mergeActivityId, companyId, userId } =
input;
// Round at the persist boundary: a merge of a 0.30000000000000004 float
// child settles the parent back to a clean quantity and lets the drain-to-
// zero short-circuit compare exactly.
const merge = round(mergeQuantity);
const childQty = round(child.quantity);
if (merge <= 0) {
throw new Error(
`buildMergeRecords: mergeQuantity must be > 0, got ${mergeQuantity}`
);
}
if (merge > childQty) {
throw new Error(
`buildMergeRecords: mergeQuantity (${mergeQuantity}) exceeds child quantity (${child.quantity})`
);
}
const childRemaining = round(childQty - merge);
return {
activityInsert: {
id: mergeActivityId,
type: "Merge",
attributes: {
"Merged Quantity": merge,
"Merged From Entity ID": child.id
},
companyId,
createdBy: userId
},
activityInputInsert: {
trackedActivityId: mergeActivityId,
trackedEntityId: child.id,
quantity: merge,
companyId,
createdBy: userId
},
activityOutputInsert: {
trackedActivityId: mergeActivityId,
trackedEntityId: parent.id,
quantity: merge,
companyId,
createdBy: userId
},
parentUpdate: { quantity: round(round(parent.quantity) + merge) },
// childRemaining is already rounded, so `=== 0` is exact here — but go
// through the shared drain rule so a merge that empties a lot settles the
// same way every other quantity writer does.
childUpdate:
childRemaining <= 0
? { quantity: 0, status: "Consumed" as const }
: { quantity: childRemaining }
};
}