From ec07a01f6f7370f72f3ef82faaefdfd327e40fd7 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:00:54 +0200
Subject: [PATCH 1/6] Document module

---
 crates/fj-kernel/src/topology/builder.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/crates/fj-kernel/src/topology/builder.rs b/crates/fj-kernel/src/topology/builder.rs
index d52832f31..3a2ec5ba1 100644
--- a/crates/fj-kernel/src/topology/builder.rs
+++ b/crates/fj-kernel/src/topology/builder.rs
@@ -1,3 +1,5 @@
+//! Convenient API to build objects
+
 use fj_math::{Circle, Line, Point, Scalar, Vector};
 
 use crate::{

From 70431bb0de1c296df9a673533ec377c0d93d0962 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:01:45 +0200
Subject: [PATCH 2/6] Move `builder` module to top-level

This is part of a reorganization of the kernel's module structure, to
prepare for some cleanup work.
---
 crates/fj-kernel/src/{topology => }/builder.rs | 3 +--
 crates/fj-kernel/src/lib.rs                    | 1 +
 crates/fj-kernel/src/topology/cycle.rs         | 3 ++-
 crates/fj-kernel/src/topology/edge.rs          | 3 ++-
 crates/fj-kernel/src/topology/face.rs          | 3 ++-
 crates/fj-kernel/src/topology/mod.rs           | 2 --
 crates/fj-kernel/src/topology/vertex.rs        | 4 +---
 7 files changed, 9 insertions(+), 10 deletions(-)
 rename crates/fj-kernel/src/{topology => }/builder.rs (99%)

diff --git a/crates/fj-kernel/src/topology/builder.rs b/crates/fj-kernel/src/builder.rs
similarity index 99%
rename from crates/fj-kernel/src/topology/builder.rs
rename to crates/fj-kernel/src/builder.rs
index 3a2ec5ba1..15176efed 100644
--- a/crates/fj-kernel/src/topology/builder.rs
+++ b/crates/fj-kernel/src/builder.rs
@@ -5,10 +5,9 @@ use fj_math::{Circle, Line, Point, Scalar, Vector};
 use crate::{
     geometry::{Curve, Surface},
     shape::{Handle, LocalForm, Shape, ValidationError, ValidationResult},
+    topology::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
 };
 
-use super::{Cycle, Edge, Face, Vertex, VerticesOfEdge};
-
 /// API for building a [`Vertex`]
 #[must_use]
 pub struct VertexBuilder<'r> {
diff --git a/crates/fj-kernel/src/lib.rs b/crates/fj-kernel/src/lib.rs
index 43e330541..6269abfcb 100644
--- a/crates/fj-kernel/src/lib.rs
+++ b/crates/fj-kernel/src/lib.rs
@@ -88,6 +88,7 @@
 #![warn(missing_docs)]
 
 pub mod algorithms;
+pub mod builder;
 pub mod geometry;
 pub mod shape;
 pub mod topology;
diff --git a/crates/fj-kernel/src/topology/cycle.rs b/crates/fj-kernel/src/topology/cycle.rs
index 005b431b0..59ed3eb02 100644
--- a/crates/fj-kernel/src/topology/cycle.rs
+++ b/crates/fj-kernel/src/topology/cycle.rs
@@ -1,9 +1,10 @@
 use crate::{
+    builder::CycleBuilder,
     geometry::Surface,
     shape::{Handle, LocalForm, Shape},
 };
 
-use super::{CycleBuilder, Edge};
+use super::Edge;
 
 /// A cycle of connected edges
 ///
diff --git a/crates/fj-kernel/src/topology/edge.rs b/crates/fj-kernel/src/topology/edge.rs
index cf0446af8..6ae3fd920 100644
--- a/crates/fj-kernel/src/topology/edge.rs
+++ b/crates/fj-kernel/src/topology/edge.rs
@@ -3,11 +3,12 @@ use std::fmt;
 use fj_math::Point;
 
 use crate::{
+    builder::EdgeBuilder,
     geometry::Curve,
     shape::{LocalForm, Shape},
 };
 
-use super::{EdgeBuilder, Vertex};
+use super::Vertex;
 
 /// An edge of a shape
 ///
diff --git a/crates/fj-kernel/src/topology/face.rs b/crates/fj-kernel/src/topology/face.rs
index 1e9f6bf8c..db83e6a3b 100644
--- a/crates/fj-kernel/src/topology/face.rs
+++ b/crates/fj-kernel/src/topology/face.rs
@@ -4,11 +4,12 @@ use fj_interop::mesh::Color;
 use fj_math::Triangle;
 
 use crate::{
+    builder::FaceBuilder,
     geometry::Surface,
     shape::{Handle, LocalForm, Shape},
 };
 
-use super::{Cycle, FaceBuilder};
+use super::Cycle;
 
 /// A face of a shape
 ///
diff --git a/crates/fj-kernel/src/topology/mod.rs b/crates/fj-kernel/src/topology/mod.rs
index c2b70833d..cc6d088c5 100644
--- a/crates/fj-kernel/src/topology/mod.rs
+++ b/crates/fj-kernel/src/topology/mod.rs
@@ -16,14 +16,12 @@
 //! definition of identity. Two [`Handle`]s are only considered equal, if they
 //! refer to objects in the same memory location.
 
-mod builder;
 mod cycle;
 mod edge;
 mod face;
 mod vertex;
 
 pub use self::{
-    builder::{CycleBuilder, EdgeBuilder, FaceBuilder, VertexBuilder},
     cycle::Cycle,
     edge::{Edge, VerticesOfEdge},
     face::{CyclesInFace, Face},
diff --git a/crates/fj-kernel/src/topology/vertex.rs b/crates/fj-kernel/src/topology/vertex.rs
index 797ead354..3f2e67a3b 100644
--- a/crates/fj-kernel/src/topology/vertex.rs
+++ b/crates/fj-kernel/src/topology/vertex.rs
@@ -2,9 +2,7 @@ use std::hash::Hash;
 
 use fj_math::Point;
 
-use crate::shape::Shape;
-
-use super::VertexBuilder;
+use crate::{builder::VertexBuilder, shape::Shape};
 
 /// A vertex
 ///

From 3a0ea5f9fc14d6e003e9693cff095233f7b0c114 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:10:27 +0200
Subject: [PATCH 3/6] Rename `topology` module to `objects`

The new name doesn't quite fit yet, but I plan to move all kinds of
objects in there, not just topological ones.
---
 crates/fj-kernel/src/algorithms/approx/cycles.rs     | 2 +-
 crates/fj-kernel/src/algorithms/approx/edges.rs      | 4 ++--
 crates/fj-kernel/src/algorithms/approx/faces.rs      | 4 ++--
 crates/fj-kernel/src/algorithms/sweep.rs             | 4 ++--
 crates/fj-kernel/src/algorithms/transform.rs         | 2 +-
 crates/fj-kernel/src/algorithms/triangulation/mod.rs | 4 ++--
 crates/fj-kernel/src/builder.rs                      | 2 +-
 crates/fj-kernel/src/lib.rs                          | 2 +-
 crates/fj-kernel/src/{topology => objects}/cycle.rs  | 0
 crates/fj-kernel/src/{topology => objects}/edge.rs   | 0
 crates/fj-kernel/src/{topology => objects}/face.rs   | 0
 crates/fj-kernel/src/{topology => objects}/mod.rs    | 0
 crates/fj-kernel/src/{topology => objects}/vertex.rs | 0
 crates/fj-kernel/src/shape/api.rs                    | 4 ++--
 crates/fj-kernel/src/shape/mapping.rs                | 2 +-
 crates/fj-kernel/src/shape/object.rs                 | 2 +-
 crates/fj-kernel/src/shape/stores.rs                 | 2 +-
 crates/fj-kernel/src/shape/validate/coherence.rs     | 4 ++--
 crates/fj-kernel/src/shape/validate/mod.rs           | 2 +-
 crates/fj-kernel/src/shape/validate/structural.rs    | 2 +-
 crates/fj-kernel/src/shape/validate/uniqueness.rs    | 2 +-
 crates/fj-operations/src/circle.rs                   | 2 +-
 crates/fj-operations/src/difference_2d.rs            | 2 +-
 crates/fj-operations/src/sketch.rs                   | 2 +-
 24 files changed, 25 insertions(+), 25 deletions(-)
 rename crates/fj-kernel/src/{topology => objects}/cycle.rs (100%)
 rename crates/fj-kernel/src/{topology => objects}/edge.rs (100%)
 rename crates/fj-kernel/src/{topology => objects}/face.rs (100%)
 rename crates/fj-kernel/src/{topology => objects}/mod.rs (100%)
 rename crates/fj-kernel/src/{topology => objects}/vertex.rs (100%)

diff --git a/crates/fj-kernel/src/algorithms/approx/cycles.rs b/crates/fj-kernel/src/algorithms/approx/cycles.rs
index 9cba6c1cf..d591fba91 100644
--- a/crates/fj-kernel/src/algorithms/approx/cycles.rs
+++ b/crates/fj-kernel/src/algorithms/approx/cycles.rs
@@ -1,6 +1,6 @@
 use fj_math::Segment;
 
-use crate::{geometry, topology::Cycle};
+use crate::{geometry, objects::Cycle};
 
 use super::{curves::approx_curve, edges::approximate_edge, Tolerance};
 
diff --git a/crates/fj-kernel/src/algorithms/approx/edges.rs b/crates/fj-kernel/src/algorithms/approx/edges.rs
index 5fd96a55a..c099b6f12 100644
--- a/crates/fj-kernel/src/algorithms/approx/edges.rs
+++ b/crates/fj-kernel/src/algorithms/approx/edges.rs
@@ -1,4 +1,4 @@
-use crate::{geometry, topology::VerticesOfEdge};
+use crate::{geometry, objects::VerticesOfEdge};
 
 pub fn approximate_edge(
     vertices: VerticesOfEdge,
@@ -36,8 +36,8 @@ mod test {
 
     use crate::{
         geometry,
+        objects::{Vertex, VerticesOfEdge},
         shape::{LocalForm, Shape},
-        topology::{Vertex, VerticesOfEdge},
     };
 
     #[test]
diff --git a/crates/fj-kernel/src/algorithms/approx/faces.rs b/crates/fj-kernel/src/algorithms/approx/faces.rs
index 5cb6afd63..c01d082e2 100644
--- a/crates/fj-kernel/src/algorithms/approx/faces.rs
+++ b/crates/fj-kernel/src/algorithms/approx/faces.rs
@@ -1,6 +1,6 @@
 use std::collections::HashSet;
 
-use crate::{geometry, topology::Face};
+use crate::{geometry, objects::Face};
 
 use super::{CycleApprox, Tolerance};
 
@@ -83,8 +83,8 @@ mod tests {
 
     use crate::{
         geometry::{self, Surface},
+        objects::Face,
         shape::Shape,
-        topology::Face,
     };
 
     use super::{CycleApprox, FaceApprox, Tolerance};
diff --git a/crates/fj-kernel/src/algorithms/sweep.rs b/crates/fj-kernel/src/algorithms/sweep.rs
index f0eaaeceb..445927867 100644
--- a/crates/fj-kernel/src/algorithms/sweep.rs
+++ b/crates/fj-kernel/src/algorithms/sweep.rs
@@ -4,8 +4,8 @@ use fj_math::{Line, Scalar, Transform, Triangle, Vector};
 
 use crate::{
     geometry::{Curve, Surface, SweptCurve},
+    objects::{Cycle, Edge, Face, Vertex},
     shape::{Handle, LocalForm, Mapping, Shape, ValidationError},
-    topology::{Cycle, Edge, Face, Vertex},
 };
 
 use super::{transform_shape, CycleApprox, Tolerance};
@@ -330,8 +330,8 @@ mod tests {
     use crate::{
         algorithms::Tolerance,
         geometry::Surface,
+        objects::Face,
         shape::{Handle, Shape},
-        topology::Face,
     };
 
     use super::sweep_shape;
diff --git a/crates/fj-kernel/src/algorithms/transform.rs b/crates/fj-kernel/src/algorithms/transform.rs
index 614c7459b..2a2e05265 100644
--- a/crates/fj-kernel/src/algorithms/transform.rs
+++ b/crates/fj-kernel/src/algorithms/transform.rs
@@ -2,8 +2,8 @@ use fj_math::Transform;
 
 use crate::{
     geometry::{Curve, Surface},
+    objects::{Face, Vertex},
     shape::{Shape, ValidationError},
-    topology::{Face, Vertex},
 };
 
 /// Transform the geometry of the shape
diff --git a/crates/fj-kernel/src/algorithms/triangulation/mod.rs b/crates/fj-kernel/src/algorithms/triangulation/mod.rs
index 06072e0b4..a0007f702 100644
--- a/crates/fj-kernel/src/algorithms/triangulation/mod.rs
+++ b/crates/fj-kernel/src/algorithms/triangulation/mod.rs
@@ -5,7 +5,7 @@ mod ray;
 use fj_interop::{debug::DebugInfo, mesh::Mesh};
 use fj_math::Point;
 
-use crate::{shape::Shape, topology::Face};
+use crate::{objects::Face, shape::Shape};
 
 use self::polygon::Polygon;
 
@@ -88,7 +88,7 @@ mod tests {
     use fj_math::{Point, Scalar};
 
     use crate::{
-        algorithms::Tolerance, geometry::Surface, shape::Shape, topology::Face,
+        algorithms::Tolerance, geometry::Surface, objects::Face, shape::Shape,
     };
 
     #[test]
diff --git a/crates/fj-kernel/src/builder.rs b/crates/fj-kernel/src/builder.rs
index 15176efed..71ae3a293 100644
--- a/crates/fj-kernel/src/builder.rs
+++ b/crates/fj-kernel/src/builder.rs
@@ -4,8 +4,8 @@ use fj_math::{Circle, Line, Point, Scalar, Vector};
 
 use crate::{
     geometry::{Curve, Surface},
+    objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
     shape::{Handle, LocalForm, Shape, ValidationError, ValidationResult},
-    topology::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
 };
 
 /// API for building a [`Vertex`]
diff --git a/crates/fj-kernel/src/lib.rs b/crates/fj-kernel/src/lib.rs
index 6269abfcb..f2f344afc 100644
--- a/crates/fj-kernel/src/lib.rs
+++ b/crates/fj-kernel/src/lib.rs
@@ -90,5 +90,5 @@
 pub mod algorithms;
 pub mod builder;
 pub mod geometry;
+pub mod objects;
 pub mod shape;
-pub mod topology;
diff --git a/crates/fj-kernel/src/topology/cycle.rs b/crates/fj-kernel/src/objects/cycle.rs
similarity index 100%
rename from crates/fj-kernel/src/topology/cycle.rs
rename to crates/fj-kernel/src/objects/cycle.rs
diff --git a/crates/fj-kernel/src/topology/edge.rs b/crates/fj-kernel/src/objects/edge.rs
similarity index 100%
rename from crates/fj-kernel/src/topology/edge.rs
rename to crates/fj-kernel/src/objects/edge.rs
diff --git a/crates/fj-kernel/src/topology/face.rs b/crates/fj-kernel/src/objects/face.rs
similarity index 100%
rename from crates/fj-kernel/src/topology/face.rs
rename to crates/fj-kernel/src/objects/face.rs
diff --git a/crates/fj-kernel/src/topology/mod.rs b/crates/fj-kernel/src/objects/mod.rs
similarity index 100%
rename from crates/fj-kernel/src/topology/mod.rs
rename to crates/fj-kernel/src/objects/mod.rs
diff --git a/crates/fj-kernel/src/topology/vertex.rs b/crates/fj-kernel/src/objects/vertex.rs
similarity index 100%
rename from crates/fj-kernel/src/topology/vertex.rs
rename to crates/fj-kernel/src/objects/vertex.rs
diff --git a/crates/fj-kernel/src/shape/api.rs b/crates/fj-kernel/src/shape/api.rs
index eb02f3242..26d55582f 100644
--- a/crates/fj-kernel/src/shape/api.rs
+++ b/crates/fj-kernel/src/shape/api.rs
@@ -2,7 +2,7 @@ use fj_math::Scalar;
 
 use crate::{
     geometry::{Curve, Surface},
-    topology::{Cycle, Edge, Face, Vertex},
+    objects::{Cycle, Edge, Face, Vertex},
 };
 
 use super::{
@@ -296,8 +296,8 @@ mod tests {
 
     use crate::{
         geometry::{Curve, Surface},
+        objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
         shape::{Handle, LocalForm, Shape, ValidationError, ValidationResult},
-        topology::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
     };
 
     #[test]
diff --git a/crates/fj-kernel/src/shape/mapping.rs b/crates/fj-kernel/src/shape/mapping.rs
index 329835db1..6944672ad 100644
--- a/crates/fj-kernel/src/shape/mapping.rs
+++ b/crates/fj-kernel/src/shape/mapping.rs
@@ -2,7 +2,7 @@ use std::collections::HashMap;
 
 use crate::{
     geometry::{Curve, Surface},
-    topology::{Cycle, Edge, Face, Vertex},
+    objects::{Cycle, Edge, Face, Vertex},
 };
 
 use super::Handle;
diff --git a/crates/fj-kernel/src/shape/object.rs b/crates/fj-kernel/src/shape/object.rs
index 29142939f..7d14eed82 100644
--- a/crates/fj-kernel/src/shape/object.rs
+++ b/crates/fj-kernel/src/shape/object.rs
@@ -1,6 +1,6 @@
 use crate::{
     geometry::{Curve, Surface},
-    topology::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
+    objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
 };
 
 use super::{
diff --git a/crates/fj-kernel/src/shape/stores.rs b/crates/fj-kernel/src/shape/stores.rs
index 9e780a98e..7f62393d6 100644
--- a/crates/fj-kernel/src/shape/stores.rs
+++ b/crates/fj-kernel/src/shape/stores.rs
@@ -10,7 +10,7 @@ use slotmap::{DefaultKey, SlotMap};
 
 use crate::{
     geometry::{Curve, Surface},
-    topology::{Cycle, Edge, Face, Vertex},
+    objects::{Cycle, Edge, Face, Vertex},
 };
 
 use super::Object;
diff --git a/crates/fj-kernel/src/shape/validate/coherence.rs b/crates/fj-kernel/src/shape/validate/coherence.rs
index 6030e4873..1d5461648 100644
--- a/crates/fj-kernel/src/shape/validate/coherence.rs
+++ b/crates/fj-kernel/src/shape/validate/coherence.rs
@@ -2,7 +2,7 @@ use std::fmt;
 
 use fj_math::{Point, Scalar};
 
-use crate::topology::Edge;
+use crate::objects::Edge;
 
 pub fn validate_edge(
     edge: &Edge<3>,
@@ -101,8 +101,8 @@ mod tests {
     use fj_math::Scalar;
 
     use crate::{
+        objects::Edge,
         shape::{LocalForm, Shape},
-        topology::Edge,
     };
 
     #[test]
diff --git a/crates/fj-kernel/src/shape/validate/mod.rs b/crates/fj-kernel/src/shape/validate/mod.rs
index 32d5bf966..ffff4d8e3 100644
--- a/crates/fj-kernel/src/shape/validate/mod.rs
+++ b/crates/fj-kernel/src/shape/validate/mod.rs
@@ -12,7 +12,7 @@ use fj_math::Scalar;
 
 use crate::{
     geometry::{Curve, Surface},
-    topology::{Cycle, Edge, Face, Vertex},
+    objects::{Cycle, Edge, Face, Vertex},
 };
 
 use super::{stores::Stores, Handle, Object};
diff --git a/crates/fj-kernel/src/shape/validate/structural.rs b/crates/fj-kernel/src/shape/validate/structural.rs
index cc37e814b..d970a1af1 100644
--- a/crates/fj-kernel/src/shape/validate/structural.rs
+++ b/crates/fj-kernel/src/shape/validate/structural.rs
@@ -2,8 +2,8 @@ use std::{collections::HashSet, fmt};
 
 use crate::{
     geometry::{Curve, Surface},
+    objects::{Cycle, Edge, Face, Vertex},
     shape::{stores::Stores, Handle},
-    topology::{Cycle, Edge, Face, Vertex},
 };
 
 pub fn validate_edge(
diff --git a/crates/fj-kernel/src/shape/validate/uniqueness.rs b/crates/fj-kernel/src/shape/validate/uniqueness.rs
index 0768c3f69..a9757bb3c 100644
--- a/crates/fj-kernel/src/shape/validate/uniqueness.rs
+++ b/crates/fj-kernel/src/shape/validate/uniqueness.rs
@@ -1,8 +1,8 @@
 use std::fmt;
 
 use crate::{
+    objects::{Edge, Vertex},
     shape::{stores::Store, Handle},
-    topology::{Edge, Vertex},
 };
 
 pub fn validate_vertex(
diff --git a/crates/fj-operations/src/circle.rs b/crates/fj-operations/src/circle.rs
index c975da62e..b568d1247 100644
--- a/crates/fj-operations/src/circle.rs
+++ b/crates/fj-operations/src/circle.rs
@@ -2,8 +2,8 @@ use fj_interop::debug::DebugInfo;
 use fj_kernel::{
     algorithms::Tolerance,
     geometry::Surface,
+    objects::{Cycle, Edge, Face},
     shape::{LocalForm, Shape, ValidationError},
-    topology::{Cycle, Edge, Face},
 };
 use fj_math::{Aabb, Point, Scalar};
 
diff --git a/crates/fj-operations/src/difference_2d.rs b/crates/fj-operations/src/difference_2d.rs
index 5a36d1120..414873b8b 100644
--- a/crates/fj-operations/src/difference_2d.rs
+++ b/crates/fj-operations/src/difference_2d.rs
@@ -1,8 +1,8 @@
 use fj_interop::debug::DebugInfo;
 use fj_kernel::{
     algorithms::Tolerance,
+    objects::{Cycle, Edge, Face},
     shape::{LocalForm, Shape, ValidationError},
-    topology::{Cycle, Edge, Face},
 };
 use fj_math::Aabb;
 
diff --git a/crates/fj-operations/src/sketch.rs b/crates/fj-operations/src/sketch.rs
index 9247658fe..923e8abb8 100644
--- a/crates/fj-operations/src/sketch.rs
+++ b/crates/fj-operations/src/sketch.rs
@@ -2,8 +2,8 @@ use fj_interop::debug::DebugInfo;
 use fj_kernel::{
     algorithms::Tolerance,
     geometry::Surface,
+    objects::Face,
     shape::{Shape, ValidationError},
-    topology::Face,
 };
 use fj_math::{Aabb, Point};
 

From 4c031c1fe58168ef4de80c48bfba8699ddbe0c47 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:30:56 +0200
Subject: [PATCH 4/6] Update documentation of `objects`

---
 crates/fj-kernel/src/objects/mod.rs | 47 +++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/crates/fj-kernel/src/objects/mod.rs b/crates/fj-kernel/src/objects/mod.rs
index cc6d088c5..d3b210176 100644
--- a/crates/fj-kernel/src/objects/mod.rs
+++ b/crates/fj-kernel/src/objects/mod.rs
@@ -1,20 +1,43 @@
-//! Topological objects
+//! Objects of a shape
 //!
-//! Simplifying a bit, topology is responsible for defining how objects are
-//! related, as opposed to geometry, which is responsible for where things are.
-//!
-//! The types in this module use the types from [`crate::geometry`].
+//! Objects, in Fornjot parlance, are the elements that make up shapes. An
+//! object can be simple and just contain data (like, for example, [`Vertex`]),
+//! or they can be quite complex and refer to other objects.
 //!
 //! # Equality
 //!
-//! Equality of topological objects is defined in terms of the geometry they
-//! refer to. That means two topological objects that refer to identical
-//! geometry are considered equal, even if they contain [`Handle`]s that refer
-//! to objects in different [`Shape`] instances.
+//! Two objects, even if they are distinct and live in different memory
+//! locations, are considered equal, if the data they contain and the objects
+//! they reference are considered equal.
+//!
+//! In contrast to that, two [`Handle`]s are considered equal, only if they
+//! reference the same object, in the same memory location. This means that two
+//! objects can be considered equal, even if the [`Handle`]s they contain are
+//! not.
+//!
+//! Equality is defined like this, two cover two distinct use cases:
+//!
+//! - If you need to know whether two [`Handle`]s actually refer to the same
+//!   object in the same [`Shape`], you can compare the [`Handle`]s.
+//! - If you only need to check whether two objects look the same, but don't
+//!   care whether they are in the same shape, compare the objects directly.
+//!
+//! The second use case is common in test code.
+//!
+//! # Implementation Note
+//!
+//! The definition of equality, as detailed above, is overly complex. It is
+//! necessary though, due to the way the kernel's core data structures work.
+//! Each shape's objects are stored in a distinct [`Shape`] structure, even if
+//! there is a high amount of redundancy between those shapes.
+//!
+//! If there was a single, append-only data structure for all objects in a CAD
+//! model, in which objects were immutable, there would be no special definition
+//! of equality for objects. Unfortunately, nobody has figured out how to make
+//! this work yet.
 //!
-//! This is different from the equality of [`Handle`], which follows a strict
-//! definition of identity. Two [`Handle`]s are only considered equal, if they
-//! refer to objects in the same memory location.
+//! [`Handle`]: crate::shape::Handle
+//! [`Shape`]: crate::shape::Shape
 
 mod cycle;
 mod edge;

From b2b653385633ee0f21190693d060adc367bc9aa1 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:32:24 +0200
Subject: [PATCH 5/6] Move remaining object modules into `objects`

This leaves the `geometry` module a bit light, but I don't know where to
put its remaining sub-module. Over time, a solution will present itself,
I'm sure.
---
 crates/fj-kernel/src/algorithms/approx/curves.rs          | 2 +-
 crates/fj-kernel/src/algorithms/approx/faces.rs           | 4 ++--
 .../src/algorithms/intersection/surface_surface.rs        | 4 ++--
 crates/fj-kernel/src/algorithms/sweep.rs                  | 6 ++----
 crates/fj-kernel/src/algorithms/transform.rs              | 3 +--
 crates/fj-kernel/src/algorithms/triangulation/mod.rs      | 4 +++-
 crates/fj-kernel/src/algorithms/triangulation/polygon.rs  | 4 ++--
 crates/fj-kernel/src/builder.rs                           | 3 +--
 crates/fj-kernel/src/geometry/mod.rs                      | 8 +-------
 crates/fj-kernel/src/{geometry => objects}/curves.rs      | 0
 crates/fj-kernel/src/objects/cycle.rs                     | 3 +--
 crates/fj-kernel/src/objects/edge.rs                      | 3 +--
 crates/fj-kernel/src/objects/face.rs                      | 3 +--
 crates/fj-kernel/src/objects/mod.rs                       | 4 ++++
 .../fj-kernel/src/{geometry => objects}/surfaces/mod.rs   | 0
 .../fj-kernel/src/{geometry => objects}/surfaces/swept.rs | 4 ++--
 crates/fj-kernel/src/shape/api.rs                         | 8 ++------
 crates/fj-kernel/src/shape/mapping.rs                     | 5 +----
 crates/fj-kernel/src/shape/object.rs                      | 5 ++---
 crates/fj-kernel/src/shape/stores.rs                      | 5 +----
 crates/fj-kernel/src/shape/validate/mod.rs                | 5 +----
 crates/fj-kernel/src/shape/validate/structural.rs         | 3 +--
 crates/fj-operations/src/circle.rs                        | 3 +--
 crates/fj-operations/src/sketch.rs                        | 3 +--
 24 files changed, 34 insertions(+), 58 deletions(-)
 rename crates/fj-kernel/src/{geometry => objects}/curves.rs (100%)
 rename crates/fj-kernel/src/{geometry => objects}/surfaces/mod.rs (100%)
 rename crates/fj-kernel/src/{geometry => objects}/surfaces/swept.rs (98%)

diff --git a/crates/fj-kernel/src/algorithms/approx/curves.rs b/crates/fj-kernel/src/algorithms/approx/curves.rs
index 63b6508ab..6aaa93525 100644
--- a/crates/fj-kernel/src/algorithms/approx/curves.rs
+++ b/crates/fj-kernel/src/algorithms/approx/curves.rs
@@ -2,7 +2,7 @@ use std::cmp::max;
 
 use fj_math::{Circle, Scalar};
 
-use crate::geometry::{self, Curve};
+use crate::{geometry, objects::Curve};
 
 use super::Tolerance;
 
diff --git a/crates/fj-kernel/src/algorithms/approx/faces.rs b/crates/fj-kernel/src/algorithms/approx/faces.rs
index c01d082e2..9ac8b03a7 100644
--- a/crates/fj-kernel/src/algorithms/approx/faces.rs
+++ b/crates/fj-kernel/src/algorithms/approx/faces.rs
@@ -82,8 +82,8 @@ mod tests {
     use map_macro::set;
 
     use crate::{
-        geometry::{self, Surface},
-        objects::Face,
+        geometry,
+        objects::{Face, Surface},
         shape::Shape,
     };
 
diff --git a/crates/fj-kernel/src/algorithms/intersection/surface_surface.rs b/crates/fj-kernel/src/algorithms/intersection/surface_surface.rs
index 916e0b0e3..2ec355905 100644
--- a/crates/fj-kernel/src/algorithms/intersection/surface_surface.rs
+++ b/crates/fj-kernel/src/algorithms/intersection/surface_surface.rs
@@ -1,6 +1,6 @@
 use fj_math::{Line, Point, Scalar, Vector};
 
-use crate::geometry::{Curve, Surface};
+use crate::objects::{Curve, Surface};
 
 /// Test intersection between two surfaces
 pub fn surface_surface(a: &Surface, b: &Surface) -> Option<Curve<3>> {
@@ -60,7 +60,7 @@ fn extract_plane(surface: &Surface) -> (Vector<3>, Scalar) {
 mod tests {
     use fj_math::Transform;
 
-    use crate::geometry::{Curve, Surface};
+    use crate::objects::{Curve, Surface};
 
     use super::surface_surface;
 
diff --git a/crates/fj-kernel/src/algorithms/sweep.rs b/crates/fj-kernel/src/algorithms/sweep.rs
index 445927867..af00299b7 100644
--- a/crates/fj-kernel/src/algorithms/sweep.rs
+++ b/crates/fj-kernel/src/algorithms/sweep.rs
@@ -3,8 +3,7 @@ use std::collections::HashMap;
 use fj_math::{Line, Scalar, Transform, Triangle, Vector};
 
 use crate::{
-    geometry::{Curve, Surface, SweptCurve},
-    objects::{Cycle, Edge, Face, Vertex},
+    objects::{Curve, Cycle, Edge, Face, Surface, SweptCurve, Vertex},
     shape::{Handle, LocalForm, Mapping, Shape, ValidationError},
 };
 
@@ -329,8 +328,7 @@ mod tests {
 
     use crate::{
         algorithms::Tolerance,
-        geometry::Surface,
-        objects::Face,
+        objects::{Face, Surface},
         shape::{Handle, Shape},
     };
 
diff --git a/crates/fj-kernel/src/algorithms/transform.rs b/crates/fj-kernel/src/algorithms/transform.rs
index 2a2e05265..45a0c9a5a 100644
--- a/crates/fj-kernel/src/algorithms/transform.rs
+++ b/crates/fj-kernel/src/algorithms/transform.rs
@@ -1,8 +1,7 @@
 use fj_math::Transform;
 
 use crate::{
-    geometry::{Curve, Surface},
-    objects::{Face, Vertex},
+    objects::{Curve, Face, Surface, Vertex},
     shape::{Shape, ValidationError},
 };
 
diff --git a/crates/fj-kernel/src/algorithms/triangulation/mod.rs b/crates/fj-kernel/src/algorithms/triangulation/mod.rs
index a0007f702..09a503ebf 100644
--- a/crates/fj-kernel/src/algorithms/triangulation/mod.rs
+++ b/crates/fj-kernel/src/algorithms/triangulation/mod.rs
@@ -88,7 +88,9 @@ mod tests {
     use fj_math::{Point, Scalar};
 
     use crate::{
-        algorithms::Tolerance, geometry::Surface, objects::Face, shape::Shape,
+        algorithms::Tolerance,
+        objects::{Face, Surface},
+        shape::Shape,
     };
 
     #[test]
diff --git a/crates/fj-kernel/src/algorithms/triangulation/polygon.rs b/crates/fj-kernel/src/algorithms/triangulation/polygon.rs
index 5630b876f..f813a7a13 100644
--- a/crates/fj-kernel/src/algorithms/triangulation/polygon.rs
+++ b/crates/fj-kernel/src/algorithms/triangulation/polygon.rs
@@ -1,7 +1,7 @@
 use fj_interop::debug::{DebugInfo, TriangleEdgeCheck};
 use fj_math::{Point, PolyChain, Segment};
 
-use crate::geometry::Surface;
+use crate::objects::Surface;
 
 use super::ray::{Hit, HorizontalRayToTheRight};
 
@@ -221,7 +221,7 @@ mod tests {
     use fj_interop::debug::DebugInfo;
     use fj_math::{Point, PolyChain};
 
-    use crate::geometry::Surface;
+    use crate::objects::Surface;
 
     use super::Polygon;
 
diff --git a/crates/fj-kernel/src/builder.rs b/crates/fj-kernel/src/builder.rs
index 71ae3a293..7e62f59b7 100644
--- a/crates/fj-kernel/src/builder.rs
+++ b/crates/fj-kernel/src/builder.rs
@@ -3,8 +3,7 @@
 use fj_math::{Circle, Line, Point, Scalar, Vector};
 
 use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
+    objects::{Curve, Cycle, Edge, Face, Surface, Vertex, VerticesOfEdge},
     shape::{Handle, LocalForm, Shape, ValidationError, ValidationResult},
 };
 
diff --git a/crates/fj-kernel/src/geometry/mod.rs b/crates/fj-kernel/src/geometry/mod.rs
index c965245d1..322d1b288 100644
--- a/crates/fj-kernel/src/geometry/mod.rs
+++ b/crates/fj-kernel/src/geometry/mod.rs
@@ -5,12 +5,6 @@
 //! [`crate::topology`], which are responsible for defining how objects are
 //! related.
 
-mod curves;
 mod points;
-mod surfaces;
 
-pub use self::{
-    curves::Curve,
-    points::Point,
-    surfaces::{Surface, SweptCurve},
-};
+pub use self::points::Point;
diff --git a/crates/fj-kernel/src/geometry/curves.rs b/crates/fj-kernel/src/objects/curves.rs
similarity index 100%
rename from crates/fj-kernel/src/geometry/curves.rs
rename to crates/fj-kernel/src/objects/curves.rs
diff --git a/crates/fj-kernel/src/objects/cycle.rs b/crates/fj-kernel/src/objects/cycle.rs
index 59ed3eb02..dc2927cb2 100644
--- a/crates/fj-kernel/src/objects/cycle.rs
+++ b/crates/fj-kernel/src/objects/cycle.rs
@@ -1,10 +1,9 @@
 use crate::{
     builder::CycleBuilder,
-    geometry::Surface,
     shape::{Handle, LocalForm, Shape},
 };
 
-use super::Edge;
+use super::{Edge, Surface};
 
 /// A cycle of connected edges
 ///
diff --git a/crates/fj-kernel/src/objects/edge.rs b/crates/fj-kernel/src/objects/edge.rs
index 6ae3fd920..a08582adf 100644
--- a/crates/fj-kernel/src/objects/edge.rs
+++ b/crates/fj-kernel/src/objects/edge.rs
@@ -4,11 +4,10 @@ use fj_math::Point;
 
 use crate::{
     builder::EdgeBuilder,
-    geometry::Curve,
     shape::{LocalForm, Shape},
 };
 
-use super::Vertex;
+use super::{Curve, Vertex};
 
 /// An edge of a shape
 ///
diff --git a/crates/fj-kernel/src/objects/face.rs b/crates/fj-kernel/src/objects/face.rs
index db83e6a3b..1f0788c6b 100644
--- a/crates/fj-kernel/src/objects/face.rs
+++ b/crates/fj-kernel/src/objects/face.rs
@@ -5,11 +5,10 @@ use fj_math::Triangle;
 
 use crate::{
     builder::FaceBuilder,
-    geometry::Surface,
     shape::{Handle, LocalForm, Shape},
 };
 
-use super::Cycle;
+use super::{Cycle, Surface};
 
 /// A face of a shape
 ///
diff --git a/crates/fj-kernel/src/objects/mod.rs b/crates/fj-kernel/src/objects/mod.rs
index d3b210176..e28d5a3db 100644
--- a/crates/fj-kernel/src/objects/mod.rs
+++ b/crates/fj-kernel/src/objects/mod.rs
@@ -39,14 +39,18 @@
 //! [`Handle`]: crate::shape::Handle
 //! [`Shape`]: crate::shape::Shape
 
+mod curves;
 mod cycle;
 mod edge;
 mod face;
+mod surfaces;
 mod vertex;
 
 pub use self::{
+    curves::Curve,
     cycle::Cycle,
     edge::{Edge, VerticesOfEdge},
     face::{CyclesInFace, Face},
+    surfaces::{Surface, SweptCurve},
     vertex::Vertex,
 };
diff --git a/crates/fj-kernel/src/geometry/surfaces/mod.rs b/crates/fj-kernel/src/objects/surfaces/mod.rs
similarity index 100%
rename from crates/fj-kernel/src/geometry/surfaces/mod.rs
rename to crates/fj-kernel/src/objects/surfaces/mod.rs
diff --git a/crates/fj-kernel/src/geometry/surfaces/swept.rs b/crates/fj-kernel/src/objects/surfaces/swept.rs
similarity index 98%
rename from crates/fj-kernel/src/geometry/surfaces/swept.rs
rename to crates/fj-kernel/src/objects/surfaces/swept.rs
index d3458126f..a5997871e 100644
--- a/crates/fj-kernel/src/geometry/surfaces/swept.rs
+++ b/crates/fj-kernel/src/objects/surfaces/swept.rs
@@ -1,6 +1,6 @@
 use fj_math::{Line, Point, Transform, Vector};
 
-use crate::geometry::Curve;
+use crate::objects::Curve;
 
 /// A surface that was swept from a curve
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
@@ -74,7 +74,7 @@ mod tests {
 
     use fj_math::{Line, Point, Vector};
 
-    use crate::geometry::Curve;
+    use crate::objects::Curve;
 
     use super::SweptCurve;
 
diff --git a/crates/fj-kernel/src/shape/api.rs b/crates/fj-kernel/src/shape/api.rs
index 26d55582f..7070a83cf 100644
--- a/crates/fj-kernel/src/shape/api.rs
+++ b/crates/fj-kernel/src/shape/api.rs
@@ -1,9 +1,6 @@
 use fj_math::Scalar;
 
-use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex},
-};
+use crate::objects::{Curve, Cycle, Edge, Face, Surface, Vertex};
 
 use super::{
     stores::{Store, Stores},
@@ -295,8 +292,7 @@ mod tests {
     use fj_math::{Point, Scalar};
 
     use crate::{
-        geometry::{Curve, Surface},
-        objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
+        objects::{Curve, Cycle, Edge, Face, Surface, Vertex, VerticesOfEdge},
         shape::{Handle, LocalForm, Shape, ValidationError, ValidationResult},
     };
 
diff --git a/crates/fj-kernel/src/shape/mapping.rs b/crates/fj-kernel/src/shape/mapping.rs
index 6944672ad..3cd317f4e 100644
--- a/crates/fj-kernel/src/shape/mapping.rs
+++ b/crates/fj-kernel/src/shape/mapping.rs
@@ -1,9 +1,6 @@
 use std::collections::HashMap;
 
-use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex},
-};
+use crate::objects::{Curve, Cycle, Edge, Face, Surface, Vertex};
 
 use super::Handle;
 
diff --git a/crates/fj-kernel/src/shape/object.rs b/crates/fj-kernel/src/shape/object.rs
index 7d14eed82..a85bc20d2 100644
--- a/crates/fj-kernel/src/shape/object.rs
+++ b/crates/fj-kernel/src/shape/object.rs
@@ -1,6 +1,5 @@
-use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex, VerticesOfEdge},
+use crate::objects::{
+    Curve, Cycle, Edge, Face, Surface, Vertex, VerticesOfEdge,
 };
 
 use super::{
diff --git a/crates/fj-kernel/src/shape/stores.rs b/crates/fj-kernel/src/shape/stores.rs
index 7f62393d6..8cf10cd4e 100644
--- a/crates/fj-kernel/src/shape/stores.rs
+++ b/crates/fj-kernel/src/shape/stores.rs
@@ -8,10 +8,7 @@ use anymap::AnyMap;
 use parking_lot::{RwLock, RwLockReadGuard};
 use slotmap::{DefaultKey, SlotMap};
 
-use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex},
-};
+use crate::objects::{Curve, Cycle, Edge, Face, Surface, Vertex};
 
 use super::Object;
 
diff --git a/crates/fj-kernel/src/shape/validate/mod.rs b/crates/fj-kernel/src/shape/validate/mod.rs
index ffff4d8e3..6882d9da5 100644
--- a/crates/fj-kernel/src/shape/validate/mod.rs
+++ b/crates/fj-kernel/src/shape/validate/mod.rs
@@ -10,10 +10,7 @@ pub use self::{
 
 use fj_math::Scalar;
 
-use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex},
-};
+use crate::objects::{Curve, Cycle, Edge, Face, Surface, Vertex};
 
 use super::{stores::Stores, Handle, Object};
 
diff --git a/crates/fj-kernel/src/shape/validate/structural.rs b/crates/fj-kernel/src/shape/validate/structural.rs
index d970a1af1..59b6279df 100644
--- a/crates/fj-kernel/src/shape/validate/structural.rs
+++ b/crates/fj-kernel/src/shape/validate/structural.rs
@@ -1,8 +1,7 @@
 use std::{collections::HashSet, fmt};
 
 use crate::{
-    geometry::{Curve, Surface},
-    objects::{Cycle, Edge, Face, Vertex},
+    objects::{Curve, Cycle, Edge, Face, Surface, Vertex},
     shape::{stores::Stores, Handle},
 };
 
diff --git a/crates/fj-operations/src/circle.rs b/crates/fj-operations/src/circle.rs
index b568d1247..7d1c56827 100644
--- a/crates/fj-operations/src/circle.rs
+++ b/crates/fj-operations/src/circle.rs
@@ -1,8 +1,7 @@
 use fj_interop::debug::DebugInfo;
 use fj_kernel::{
     algorithms::Tolerance,
-    geometry::Surface,
-    objects::{Cycle, Edge, Face},
+    objects::{Cycle, Edge, Face, Surface},
     shape::{LocalForm, Shape, ValidationError},
 };
 use fj_math::{Aabb, Point, Scalar};
diff --git a/crates/fj-operations/src/sketch.rs b/crates/fj-operations/src/sketch.rs
index 923e8abb8..f9f24256c 100644
--- a/crates/fj-operations/src/sketch.rs
+++ b/crates/fj-operations/src/sketch.rs
@@ -1,8 +1,7 @@
 use fj_interop::debug::DebugInfo;
 use fj_kernel::{
     algorithms::Tolerance,
-    geometry::Surface,
-    objects::Face,
+    objects::{Face, Surface},
     shape::{Shape, ValidationError},
 };
 use fj_math::{Aabb, Point};

From 831a18a29804aedd7f3663a2d2bce51e1ec8126d Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Tue, 14 Jun 2022 14:33:35 +0200
Subject: [PATCH 6/6] Update documentation of `geometry` module

---
 crates/fj-kernel/src/geometry/mod.rs | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/crates/fj-kernel/src/geometry/mod.rs b/crates/fj-kernel/src/geometry/mod.rs
index 322d1b288..39d98cd21 100644
--- a/crates/fj-kernel/src/geometry/mod.rs
+++ b/crates/fj-kernel/src/geometry/mod.rs
@@ -1,9 +1,4 @@
-//! Geometry objects
-//!
-//! Simplifying a bit, geometry is responsible for where things are, but now how
-//! they are related. The types in this module are referred to by the types in
-//! [`crate::topology`], which are responsible for defining how objects are
-//! related.
+//! Miscellaneous geometry code
 
 mod points;