Topology language reference

Root namespaces

Root	Topology kind
`topology.faces`	face
`topology.edges`	edge
`topology.vertices`	vertex

All roots expose all, createdBy, modifiedBy, and persistentReference.

Predicates

Kind	Predicate	Arguments
Face	`surface`	backend surface-kind string
Face	`normal`	scalar direction, optional angular tolerance (default `deg(0.1)`)
Face	`radius`	length, optional linear tolerance (default `mm(1e-6)`)
Face	`adjacentTo`	completed edge selection
Edge	`curve`	backend curve-kind string
Edge	`direction`	scalar direction, optional angular tolerance (default `deg(0.1)`)
Edge	`radius`	length, optional linear tolerance (default `mm(1e-6)`)
Edge	`adjacentTo`	completed face or vertex selection
Vertex	`position`	3D length vector, optional linear tolerance (default `mm(1e-6)`)
Vertex	`adjacentTo`	completed edge selection

Surface and curve strings are kernel descriptor kinds. Prefer semantic origin/role filters for modeled intent when possible.

Tolerances and orientation

normal and direction match when the angle between the requested vector and the descriptor’s vector is at most the angular tolerance. The requested vector need not be unit length, but it cannot be zero.

Face normal is oriented. It compares against the face normal the kernel reports, which is outward for planar faces on the OCCT backend, so normal(scalarVec3(0, 0, 1)) and normal(scalarVec3(0, 0, -1)) select opposite faces.
Edge direction ignores sign. direction(scalarVec3(1, 0, 0)) and direction(scalarVec3(-1, 0, 0)) select the same edges.
radius matches when the descriptor radius differs from the requested radius by at most the linear tolerance.
position applies its linear tolerance to each axis separately. A vertex matches when every coordinate is within the tolerance, which is a box around the requested point rather than a sphere.

Only items whose descriptor reports the compared value can match. The OCCT backend reports normals for planar faces, directions for line edges, and radii for cylindrical faces and circular edges. Tolerances must be positive and finite; any other value fails with TOPOLOGY_SELECTOR_INVALID.

Origin options

createdBy(feature, {
  role?: FaceTopologyRole | EdgeTopologyRole,
  source?: {
    sketch: ProfileRef,
    entity: string,
  },
})

Vertices currently have no invented semantic corner roles; their origin lineage can still participate where the backend provides it.

Algebra

Every TopologyQuery<K> supports:

query.and(other, ...more)
query.or(other, ...more)
query.not()

Operands must share topology kind. Canonicalization flattens nested equal operators, removes exact duplicates, and sorts their IR representation.

Completion/cardinality

Method	Required match count
`select()`	exactly 1
`exactly(n)`	exactly `n`
`atLeast(n)`	`n` or more
`between(min, max)`	inclusive bounded range

Counts are positive safe integers, at most Number.MAX_SAFE_INTEGER, and a maximum cannot be less than its minimum. The builder throws a RangeError for any other count. validateDocument and selection resolution reject such a selection with TOPOLOGY_SELECTOR_INVALID, and document parsing rejects it with IR_INVALID. There is no zero-match completed selection in the current feature authoring surface.

Persistent atom

topology.faces.persistentReference(faceReference)

The reference topology kind must match the root. The atom can compose through the full query algebra and adjacency. During feature authoring, every persistent reference must target that consuming feature’s direct input solid.

Resolution outcomes

Ordinary selection resolution returns keys only when cardinality is satisfied. Missing and ambiguous diagnostics include a frozen explanation report. Direct explainTopologySelection turns only the outermost selection’s resolved, missing, or ambiguous outcome into a successful report. Everything else stays a failed result:

a malformed selection or query input (TOPOLOGY_SELECTOR_INVALID)
any nested adjacentTo selection that is itself missing or ambiguous
any persistent-atom failure
an origin query against partial history (TOPOLOGY_HISTORY_UNAVAILABLE)
an exhausted operational limit
a malformed kernel snapshot (KERNEL_ERROR with protocolViolation: true)

Selector input is never reported as a kernel fault. Resolution rejects a missing or unknown query operator, an and or or without operands, a not without its query, an adjacentTo without its selection, an invalid count, a zero normal or direction vector, and an invalid tolerance with TOPOLOGY_SELECTOR_INVALID, whether it finds the problem before or after reading the snapshot. The direct functions do not schema-check every leaf field, so hand-built IR with a missing leaf field, such as a surface query without a kind, can match nothing and report a missing selection instead. Selections built with the topology builders or read by parseDocument are always well formed. Persistent resolution distinguishes:

exact compatible unique match
missing match
ambiguous match
malformed evidence
incompatible protocol/fingerprint
exhausted operational limit
malformed kernel snapshot

Logical operators never downgrade one of the latter failures to an empty set.

Key scope

Resolved keys belong to the current evaluated topology snapshot. Do not serialize them, compare them across runs, or treat their string representation as an ordering/identity protocol.

Library reference

Tools and formats

Exhaustive guide