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.
/**
* Sub-assemblies: pure structure over an instruction's steps. No three.js.
*
* Steps arrive in PLAY order (`sortOrder`). A sub-assembly is a header step
* (`isSubAssembly`) plus the steps whose `parentStepId` is the header; those
* steps sit directly before their header. A header's `usedInStepId` names the
* later step that fits the finished unit; without one, the header itself is
* where the unit joins the main build.
*
* Shared by the player (numbering, isolation, carry-in), the ERP editor
* (step list, which actions to offer) and the ERP service (write validation),
* so all three answer the same question the same way.
*/
import type { AssemblyStep, Motion } from "./types";
type StructureStep = Pick<
AssemblyStep,
"id" | "componentNodeIds" | "parentStepId" | "usedInStepId" | "isSubAssembly"
>;
export type SubAssemblyInfo = {
stepId: string;
/** Members: their header. Headers: themselves. Main-build steps: null. */
headerId: string | null;
isHeader: boolean;
/** "1", "4.2": top level counts headers and main-build steps in display order. */
number: string;
/** False only for a header something uses: that unit joins at the using step. */
plays: boolean;
/** Members: every part of their sub-assembly (shown on its own). Otherwise null. */
isolatePartIds: string[] | null;
/** Headers: every part of the finished unit. Otherwise null. */
unitPartIds: string[] | null;
/** Headers whose finished parts arrive at this step. */
carriesIn: string[];
};
export const isSubAssemblyHeader = (
step: Pick<AssemblyStep, "isSubAssembly">
) => step.isSubAssembly === true;
function membersOf(steps: StructureStep[], headerId: string) {
return steps.filter((step) => step.parentStepId === headerId);
}
/**
* Every part a sub-assembly contains: what its steps install, plus the parts of
* every sub-assembly those steps use (a gear train used inside a heel module).
*/
export function subAssemblyPartIds(
steps: StructureStep[],
headerId: string,
seen: Set<string> = new Set()
): string[] {
if (seen.has(headerId)) return [];
seen.add(headerId);
const parts = new Set<string>();
for (const member of membersOf(steps, headerId)) {
for (const id of member.componentNodeIds) parts.add(id);
for (const used of steps) {
if (isSubAssemblyHeader(used) && used.usedInStepId === member.id) {
for (const id of subAssemblyPartIds(steps, used.id, seen))
parts.add(id);
}
}
}
return [...parts];
}
/**
* The build each step happens in, keyed by step id: its sub-assembly's header
* id, or `null` for the main build. Headers themselves are main-build steps
* (an unused one is where its unit joins the main build).
*/
export function stepWorlds(steps: StructureStep[]): Map<string, string | null> {
const byId = new Map(steps.map((step) => [step.id, step]));
return new Map(steps.map((step) => [step.id, worldIn(byId, step)]));
}
function worldIn(
byId: ReadonlyMap<string, StructureStep>,
step: StructureStep
): string | null {
if (!step.parentStepId || isSubAssemblyHeader(step)) return null;
const header = byId.get(step.parentStepId);
return header && isSubAssemblyHeader(header) ? header.id : null;
}
/**
* When each part shows up in a given build (`world`): a part installed there
* appears at its own step; a finished sub-assembly's parts appear at the step
* that carries the unit into that build (following uses outward, so a gear
* train used in a heel module reaches the main build when the heel module
* does). Parts that never reach `world` are absent from the map.
*/
export function arrivalIndexByNode(
steps: StructureStep[],
world: string | null
): Map<string, number> {
const indexById = new Map(steps.map((step, index) => [step.id, index]));
const byId = new Map(steps.map((step) => [step.id, step]));
const worlds = stepWorlds(steps);
const arrival = new Map<string, number>();
steps.forEach((installer) => {
if (installer.componentNodeIds.length === 0) return;
let current: StructureStep | undefined = installer;
for (let hops = 0; current && hops <= steps.length; hops++) {
const here: string | null = worlds.get(current.id) ?? null;
if (here === world) {
const index = indexById.get(current.id)!;
for (const nodeId of installer.componentNodeIds) {
if (!arrival.has(nodeId)) arrival.set(nodeId, index);
}
return;
}
// Already in the main build and still not in `world`: it never gets there.
if (here === null) return;
const header = byId.get(here);
if (!header) return;
current = header.usedInStepId ? byId.get(header.usedInStepId) : header;
}
});
return arrival;
}
/**
* The step list's rows: each header directly above its members (members are
* stored before it), everything else in play order.
*/
export function displayOrder(
steps: StructureStep[]
): { stepId: string; depth: 0 | 1 }[] {
const rows: { stepId: string; depth: 0 | 1 }[] = [];
const emitted = new Set<string>();
const byId = new Map(steps.map((step) => [step.id, step]));
for (const step of steps) {
if (emitted.has(step.id)) continue;
const parent = step.parentStepId ? byId.get(step.parentStepId) : undefined;
const header = isSubAssemblyHeader(step) ? step : parent;
if (header && isSubAssemblyHeader(header) && !emitted.has(header.id)) {
rows.push({ stepId: header.id, depth: 0 });
emitted.add(header.id);
for (const member of membersOf(steps, header.id)) {
rows.push({ stepId: member.id, depth: 1 });
emitted.add(member.id);
}
continue;
}
rows.push({ stepId: step.id, depth: 0 });
emitted.add(step.id);
}
return rows;
}
export function buildSubAssemblyPlan(
steps: StructureStep[]
): Map<string, SubAssemblyInfo> {
const plan = new Map<string, SubAssemblyInfo>();
const byId = new Map(steps.map((step) => [step.id, step]));
const partsByHeader = new Map<string, string[]>();
const partsOf = (headerId: string) => {
let parts = partsByHeader.get(headerId);
if (!parts) {
parts = subAssemblyPartIds(steps, headerId);
partsByHeader.set(headerId, parts);
}
return parts;
};
let top = 0;
let child = 0;
for (const { stepId, depth } of displayOrder(steps)) {
const step = byId.get(stepId)!;
const isHeader = isSubAssemblyHeader(step);
if (depth === 0) {
top += 1;
child = 0;
} else {
child += 1;
}
const headerId = isHeader
? step.id
: depth === 1
? (step.parentStepId ?? null)
: null;
const carriesIn = steps
.filter((s) => isSubAssemblyHeader(s) && s.usedInStepId === step.id)
.map((s) => s.id);
if (isHeader && !step.usedInStepId) carriesIn.push(step.id);
plan.set(step.id, {
stepId: step.id,
headerId,
isHeader,
number: depth === 0 ? String(top) : `${top}.${child}`,
plays: !(isHeader && step.usedInStepId),
isolatePartIds: depth === 1 && headerId ? partsOf(headerId) : null,
unitPartIds: isHeader ? partsOf(step.id) : null,
carriesIn
});
}
return plan;
}
/** A finished sub-assembly that joins on a path of its own (its header's motion). */
export type PathUnit = { headerId: string; nodeIds: string[]; motion: Motion };
/**
* How a step's parts move. The finished sub-assemblies it carries in either
* fly their own path (`pathUnits`) or glide in beside the build; everything
* else rides the step's own insertion.
*/
export type CarryPlan = {
/** The units with a path of their own, in sub-assembly order: they fly in first. */
pathUnits: PathUnit[];
/** Carried parts with no path of their own: they glide in beside the build. */
glidingPartIds: string[];
/** What the step's own insertion moves: its own parts plus the gliding units. */
ownMovingPartIds: string[];
/**
* An unused header whose unit joins the main build on its own path: that
* path IS the header's motion, so the header has no insertion of its own.
*/
joinsOnOwnPath: boolean;
};
export function carriesUnits(plan: CarryPlan): boolean {
return plan.pathUnits.length > 0 || plan.glidingPartIds.length > 0;
}
/**
* Per step (same order as `steps`), from the plan `buildSubAssemblyPlan`
* made for the same steps. A header whose `motion` is not `none` has a path
* of its own; the rest keep the glide from beside the build.
*/
export function buildCarryPlans(
steps: (StructureStep & Pick<AssemblyStep, "motion">)[],
subPlan: Map<string, SubAssemblyInfo>
): CarryPlan[] {
const byId = new Map(steps.map((step) => [step.id, step]));
return steps.map((step) => {
const pathUnits: PathUnit[] = [];
const gliding = new Set<string>();
for (const headerId of subPlan.get(step.id)?.carriesIn ?? []) {
const nodeIds = subPlan.get(headerId)?.unitPartIds ?? [];
const header = byId.get(headerId);
if (header && header.motion.type !== "none") {
pathUnits.push({ headerId, nodeIds, motion: header.motion });
} else {
for (const id of nodeIds) gliding.add(id);
}
}
const onPath = new Set(pathUnits.flatMap((unit) => unit.nodeIds));
for (const id of onPath) gliding.delete(id);
const own = new Set([...step.componentNodeIds, ...gliding]);
for (const id of onPath) own.delete(id);
return {
pathUnits,
glidingPartIds: [...gliding],
ownMovingPartIds: [...own],
joinsOnOwnPath: pathUnits.some((unit) => unit.headerId === step.id)
};
});
}
export type SubAssemblyRule = 1 | 2 | 3;
export type SubAssemblyViolation = {
stepId: string;
rule: SubAssemblyRule;
message: string;
};
/**
* The structural rules, checked on every write:
* 1. a sub-assembly's steps sit directly before its header;
* 2. no nesting: only headers have members, and headers are never members;
* 3. a header is used by a later, ordinary step that is not one of its own.
*/
export function validateSubAssemblies(
steps: StructureStep[]
): SubAssemblyViolation[] {
const violations: SubAssemblyViolation[] = [];
const indexById = new Map(steps.map((step, index) => [step.id, index]));
const byId = new Map(steps.map((step) => [step.id, step]));
steps.forEach((step, index) => {
if (step.parentStepId) {
const header = byId.get(step.parentStepId);
if (!header || !isSubAssemblyHeader(header)) {
violations.push({
stepId: step.id,
rule: 2,
message: "A step can only belong to a sub-assembly"
});
} else if (isSubAssemblyHeader(step)) {
violations.push({
stepId: step.id,
rule: 2,
message: "A sub-assembly can't be inside another sub-assembly"
});
}
}
if (!isSubAssemblyHeader(step)) {
if (step.usedInStepId) {
violations.push({
stepId: step.id,
rule: 3,
message: "Only a sub-assembly can be used in a step"
});
}
return;
}
const members = membersOf(steps, step.id);
const contiguous = members.every(
(member, i) => indexById.get(member.id) === index - members.length + i
);
if (!contiguous) {
violations.push({
stepId: step.id,
rule: 1,
message: "A sub-assembly's steps must come directly before it"
});
}
if (step.usedInStepId) {
const target = byId.get(step.usedInStepId);
const targetIndex = indexById.get(step.usedInStepId);
if (!target || targetIndex === undefined) {
violations.push({
stepId: step.id,
rule: 3,
message: "The step using this sub-assembly doesn't exist"
});
} else if (isSubAssemblyHeader(target)) {
violations.push({
stepId: step.id,
rule: 3,
message:
"A sub-assembly is used in a step, not in another sub-assembly"
});
} else if (target.parentStepId === step.id) {
violations.push({
stepId: step.id,
rule: 3,
message: "A sub-assembly can't be used by one of its own steps"
});
} else if (targetIndex < index) {
violations.push({
stepId: step.id,
rule: 3,
message: "A sub-assembly can only be used after it is built"
});
}
}
});
return violations;
}
export type UnusableReason = "header" | "own" | "before";
/** The sub-assemblies a step could use, with why each one can't be. */
export function usableSubAssemblies(
steps: StructureStep[],
stepId: string
): { headerId: string; reason: UnusableReason | null }[] {
const index = steps.findIndex((step) => step.id === stepId);
const step = steps[index];
if (!step) return [];
return steps
.map((header, headerIndex) => ({ header, headerIndex }))
.filter(({ header }) => isSubAssemblyHeader(header))
.map(({ header, headerIndex }) => ({
headerId: header.id,
reason: isSubAssemblyHeader(step)
? "header"
: step.parentStepId === header.id
? "own"
: index < headerIndex
? "before"
: null
}));
}