Persistent topology references

Persistent references are for intent that must survive beyond one evaluation. They store bounded, versioned evidence—not a native shape, pointer, face index, or evaluation key.

When to use them

Use an ordinary semantic selection when a stable role and source already describe the intended item. Use a persistent reference when the user selects a specific item interactively or when no unique semantic query can be authored up front. Capture still has to prove that the stored evidence identifies exactly one item. When the snapshot has complete history, an item’s role or sketch-source creation anchor is authoritative (see How resolution works), and geometry is not used to tell apart items that share the same anchor. Such items cannot be captured: capture fails with TOPOLOGY_MATCH_AMBIGUOUS. This applies whenever several items in one result carry the same source-free class role, such as extrude.edge.lateral, loft.edge.lateral, sweep.edge.lateral, fillet.face.blend, or chamfer.face.bevel. It also applies to the side faces and rims of a multi-curve profile that has no sketch sources, and to the sweep side faces that one profile curve produces along several path segments. For example, one lateral edge of an extruded rectangle cannot be captured on the default OCCT kernel, which has complete extrusion history. Select such an item with a semantic query instead, for example the lateral edge adjacent to two source-anchored side faces.

Complete capture, resolution, and explanation workflow

This exact-OCCT module captures a semantically named face, changes the model, resolves the detached evidence against the new snapshot, and inspects the bounded explanation.

import {
  captureTopologyReference,
  explainTopologyReference,
  resolveTopologyReference,
  type CadResult,
  type KernelShape,
  type PersistentTopologyReference,
} from "invariantcad";
import { createOcctKernel } from "invariantcad/kernels/occt";

function valueOrThrow<T>(result: CadResult<T>): T {
  if (!result.ok) {
    throw new Error(
      result.diagnostics.map((item) => item.message).join("\n"),
    );
  }
  return result.value;
}

async function captureAndResolve() {
  const kernel = await createOcctKernel();
  const signatures = kernel.capabilities.topology?.signatures;
  if (
    signatures === undefined ||
    kernel.box === undefined ||
    kernel.topology === undefined
  ) {
    kernel.dispose();
    throw new Error("The selected kernel lacks exact topology support");
  }

  let firstShape: KernelShape | undefined;
  let changedShape: KernelShape | undefined;
  try {
    firstShape = kernel.box([10, 20, 30], false, { feature: "box" });
    const first = kernel.topology(firstShape);
    const face = first.faces.find((item) =>
      item.lineage.some((entry) => entry.role === "box.face.x-min"),
    );
    if (face === undefined) {
      throw new Error("The expected semantic face was not present");
    }
    const reference: PersistentTopologyReference<"face"> = valueOrThrow(
      captureTopologyReference(first, "face", face.key, {
        capabilities: signatures,
        tolerance: {
          linear: 1e-6,
          angular: 1e-9,
          relative: 1e-9,
        },
      }),
    );

    changedShape = kernel.box([16, 20, 30], false, { feature: "box" });
    const changed = kernel.topology(changedShape);
    const resolved = valueOrThrow(
      resolveTopologyReference(reference, changed, {
        capabilities: signatures,
      }),
    );
    const explanation = valueOrThrow(
      explainTopologyReference(reference, changed, {
        capabilities: signatures,
      }),
    );
    return {
      protocolVersion: reference.protocolVersion,
      outcome: explanation.outcome,
      evidence:
        explanation.outcome === "resolved"
          ? explanation.evidence
          : null,
      candidatesMatched: explanation.candidatesMatched,
      keyChanged: resolved.key !== face.key,
      capturedKeyStored: JSON.stringify(reference).includes(face.key),
    };
  } finally {
    if (changedShape !== undefined) {
      kernel.disposeShape(changedShape);
    }
    if (firstShape !== undefined) {
      kernel.disposeShape(firstShape);
    }
    kernel.dispose();
  }
}

export const persistentTopologySummary = await captureAndResolve();
console.log(persistentTopologySummary);

The release gate compiles and executes the source module from examples/docs/persistent-topology.ts. Capture first proves the evidence uniquely identifies the selected item inside the capture snapshot. A symmetric indistinguishable item is rejected rather than assigned an arbitrary identity. Evaluation-scoped keys are never stored as durable evidence.

Register captured evidence in a design

const opening = cad.topologyReference("housing-opening", bodyRef, {
  topology: "face",
  variants: [captured.value],
});

const shell = cad.shell("housing-shell", bodyRef, {
  openings: topology.faces.persistentReference(opening).select(),
  thickness: mm(2),
  direction: "inward",
});

The registered reference is bound to bodyRef. A selector cannot consume it against an ancestor, descendant, unrelated solid, or another design.

Variants and fingerprints

A document entry may contain variants for distinct supported topology protocol and exact kernel-fingerprint combinations. Duplicate fingerprint variants are rejected. Evaluation chooses only an exact compatible variant; it never silently upgrades a stored protocol or loosens a fingerprint.

How resolution works

Validate the stored envelope and operational limits.
Check the kernel’s signature protocol and fingerprint.
Normalize one current topology snapshot.
If both snapshots have complete history and either side carries a role or sketch-source creation anchor, compare only those anchors. Exact agreement is a semantic-lineage match and any difference is a mismatch. Geometry is not consulted, even when several current items share the anchor.
Vertices have no semantic roles, but a protocol-v2 vertex can carry a sketch-source creation anchor, which step 4 compares like any other. For a vertex with no direct anchor on either side, under complete history, if every incident edge on either side is anchored, the vertex matches by semantic-lineage only when the complete incident-edge anchor sets agree one-to-one.
Otherwise, including whenever either snapshot has partial history, compare bounded toleranced geometry and one-hop adjacency evidence (geometry-adjacency).
Return a current key only for exactly one match.

No match produces TOPOLOGY_MATCH_MISSING. Multiple matches produce TOPOLOGY_MATCH_AMBIGUOUS. A fingerprint mismatch is distinct from both.

Explanations and shared sessions

Use explainTopologyReference for one detached explanation, or createTopologyReferenceResolutionSession when resolving/explaining several references against one snapshot. The session shares normalization, caches, and a cumulative work budget. An invalid persistent atom remains fatal inside and, or, not, and adjacentTo; logical operators cannot hide incompatible stored evidence.

What persistence does not mean

Persistent topology references do not provide:

a cross-run native shape cache
durable native face indices
geometric document diffing
guaranteed identity for symmetric indistinguishable peers
automatic migration to a new signature protocol

The normative stable/missing/ambiguous contract is published in the persistent-topology torture specification.

Getting started

Modeling

Evaluation

Analysis and interchange