OCCTSwift Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Swift Application                            │
│                 (RailwayCAD, or any CAD app)                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OCCTSwift (Swift API)                         │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐     │
│  │  Shape    │  │   Wire    │  │   Mesh    │  │ Exporter  │     │
│  │           │  │           │  │           │  │           │     │
│  │ - box()   │  │ - rect()  │  │ - verts   │  │ - STL     │     │
│  │ - sweep() │  │ - arc()   │  │ - normals │  │ - STEP    │     │
│  │ - union() │  │ - bspline │  │ - indices │  │           │     │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Swift calls Obj-C
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  OCCTBridge (Objective-C++)                      │
│                                                                  │
│  C-style functions with opaque handles:                          │
│  - OCCTShapeRef, OCCTWireRef, OCCTMeshRef                        │
│  - OCCTShapeCreateBox(), OCCTShapeUnion(), etc.                  │
│                                                                  │
│  Internally wraps OCCT C++ objects:                              │
│  - TopoDS_Shape, TopoDS_Wire, etc.                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ C++ calls
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                OpenCASCADE Technology (C++)                      │
│                                                                  │
│  Modules used:                                                   │
│  - TKernel, TKMath       (core utilities)                        │
│  - TKG2d, TKG3d          (2D/3D geometry)                        │
│  - TKBRep, TKTopAlgo     (B-Rep topology)                        │
│  - TKPrim                (primitive shapes)                      │
│  - TKBO                  (boolean operations)                    │
│  - TKFillet, TKOffset    (modifications)                         │
│  - TKMesh                (triangulation)                         │
│  - TKSTEP, TKSTL         (file export)                           │
└─────────────────────────────────────────────────────────────────┘

Swift Shape        OCCTShape struct       OCCT Handle
┌──────────┐       ┌──────────────┐       ┌──────────────┐
│ handle ──┼──────►│ TopoDS_Shape │──────►│ Actual data  │
└──────────┘       └──────────────┘       └──────────────┘
     │                                           ▲
     │ deinit                                    │
     ▼                                           │
OCCTShapeRelease() ─── delete struct ─── releases handle

`withHandle` is on every `NativeHandleOwner` (`Shape`, `Edge`, `Wire`, `Face` and the three
curve and surface parents), and `Scripts/check-borrowed-handle-temporaries.py` fails the build on a
`.handle` read off a subscript or a call result. An owner bound to its own `let` is not affected.
A split read, `let h = doc.handle` with the owner unused afterwards and `h` used by later calls,
did not reproduce either (variants SPL and SPS in the probe: correct 8/8 under `MallocScribble`),
so the gate does not flag it; that is a measurement, not a guarantee, and `withExtendedLifetime`
is the form that holds.

Seven public classes still expose a bare `public let handle`: `GeomPoint3D`, `GeomDirection`,
`GeomVector3D`, `Axis1Placement`, `Axis2Placement`, `Interval` and `IntervalSet`. Making them
`internal` is a source-breaking change, so each carries the rule on the property's documentation
instead; hold the owner with `withExtendedLifetime(x) { ... x.handle ... }`.
`Scripts/repro/3130-borrowed-handle/` reproduces and measures it.

Because a debug `swift test` cannot see this class, CI also runs the tests in an optimised build:
the `release-mode-tests` job runs `Scripts/release-mode-test.sh` (`subset` on a pull request, `full`
on `main`, on a manual dispatch and when a release is published) under `MallocScribble`. Run the
same thing locally with `Scripts/release-mode-test.sh subset`; the design and measurements are in
[`okf/policies/release-mode-tests.md`](../../okf/policies/release-mode-tests.md).

### A release the bridge never handed out is refused

A bridge release gives back a reference the matching create took. Giving back one it did not take
is not a no-op, so where the create hands out a raw `Standard_Transient*` the release checks an
address-keyed registry (`occtBorrowRegister` / `occtBorrowGiveBack` in `OCCTBridge_Internal.h`)
before touching the object. A null, a second release of the same pointer, or a pointer this bridge
never produced is declined and counted by `OCCTBridgeRefusedReleaseCount`.

The contract comes from OCCT, not from us. The kernel has no precedent to copy for handing a raw
`Standard_Transient*` to a foreign caller: `opencascade::handle`'s `BeginScope` and `EndScope` are
the only callers of `IncrementRefCounter` and `DecrementRefCounter` anywhere in the pinned tree, so
the handle is its whole borrow protocol. Two narrower questions it does answer decide the rest.
`EndScope` destroys only when `DecrementRefCounter()` returns zero, so the reference the bridge
holds keeps the storage alive for the whole borrow and a live object's address can never collide
with an entry already in the registry. And when a reference count says something impossible,
`Standard_Transient::This()` throws `Standard_ProgramError` in every build rather than tolerating
it. So `occtBorrowRegister` returns nothing and throws on a collision, which the create's existing
`catch` records as a diagnostic and reports as a null handle.

A release likewise does what `EndScope` does: act on the value `DecrementRefCounter()` returns and
call the virtual `Delete()`, never a second `GetRefCount()` read and never a bare `delete`. The
sources, and the answers weighed and rejected, are at the declaration.

`_Nonnull` on the declaration is not what stops the null: it is a promise the compiler does not
enforce, and section 6 above measures that a consumer can call these entry points directly.

Two defects are behind this, with the same cause and different endings. `TObj_Application` is a
process-wide singleton whose own function-local static `Handle` holds a permanent reference, so an
over-release freed nothing at the time and left the count one below the truth; the object died
later, in the next ordinary handle to fall out of scope, about 660 test lines from the call that
doomed it, as a SIGSEGV on Apple and an `indirect call type mismatch` on wasm
([#2897](https://github.com/SecondMouseAU/OCCTSwift/issues/2897)). `Message_Messenger` and
`Message_Report` have no such static, so there the first release already deletes and a second one
reads `GetRefCount()` out of freed memory and may delete the block again
([#2952](https://github.com/SecondMouseAU/OCCTSwift/issues/2952)).

The two read differently in one respect. The singleton's release refuses through a borrow *count*
and can expose `OCCTTObjApplicationRefCount`, because the object survives and its reference count
is readable across the operation. Nothing survives a correct messenger or report release, so there
the refusal itself is the only observable, which is what `OCCTBridgeRefusedReleaseCount` is for.

### Thread Safety

- OCCT is not thread-safe for shared objects
- Each `Shape` should be used from one thread
- For concurrent operations, create separate shapes

## File Organization

## Performance Considerations

### Expensive Operations

1. **Boolean operations**: O(n²) or worse; avoid in tight loops
2. **Meshing**: Depends on deflection; smaller = more triangles
3. **Sweep along complex path**: B-spline evaluation is costly

### Optimization Strategies

1. **Batch operations**: Build compound, then mesh once
2. **Cache meshes**: Don't re-mesh unchanged shapes
3. **Appropriate deflection**: 0.1mm for preview, 0.01mm for export
4. **Background threading**: Heavy operations off main thread

## Integration with SceneKit

Typical workflow:

```swift
// 1. Create geometry with OCCT
let rail = Shape.sweep(profile: railProfile, along: trackPath)

// 2. Tessellate for display
let mesh = rail.mesh(linearDeflection: 0.1)

// 3. Create SceneKit geometry
let geometry = mesh.sceneKitGeometry()
geometry.materials = [railMaterial]

// 4. Add to scene
let node = SCNNode(geometry: geometry)
scene.rootNode.addChildNode(node)