Persistent topology references

Capture detached topology evidence, store it in a document, and resolve it uniquely after design changes.

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.

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

1. Validate the stored envelope and operational limits.
2. Check the kernel’s signature protocol and fingerprint.
3. Normalize one current topology snapshot.
4. Prefer authoritative semantic lineage when complete and uniquely anchored.
5. Otherwise use bounded toleranced geometry and adjacency evidence.
6. 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.