> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={"system"}
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

```ts theme={"system"}
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](/persistent-topology-torture).