1.0.0 readiness: tag namespace, consumer testing, dedup verification, comments, structure

[gsdali]

0.3.0 ships now. 1.0.0 waits on the five items below. The picking consolidation (ecosystem#43) was the original gate and it is met, but meeting it is not the same as being ready to freeze a public API.

1. The tag namespace blocks 1.0.0 outright

This repo was built by subtree-merging OCCTSwiftTools, OCCTSwiftAIS and OCCTSwiftCADKit at their original paths, so git blame survives. That also inherited all three repos' tags: 44 in total, of which only v0.1.0, v0.2.0 and v0.3.0 point at the merged package.

The other 41 point at commits where Package.swift is still named OCCTSwiftTools or OCCTSwiftAIS. 26 of them occupy v1.0.0 through v1.6.4.

So v1.0.0 already exists, on a May 2026 OCCTSwiftTools commit, and today a consumer pinning from: "1.0.0" gets:

error: no versions of 'occtswiftinteraction' match the requirement 1.0.0..<2.0.0

It fails loudly rather than silently resolving to the wrong package, which is the better of the two failures, but 1.0.0 cannot be tagged without moving an existing tag.

Deleting the inherited tags is safe, and verified so: all three original repos still hold every one of those tags at identical commits (OCCTSwiftTools v1.6.4 and this repo's v1.6.4 are both d48a7c2), nothing in the fleet pins this package above 0.3.0, and the commits stay reachable from main either way. The alternative is starting the stable line at 2.0.0, above the highest inherited tag, which costs nothing but leaves a releases page where 41 of 45 tags belong to packages that no longer live here.

Note that v0.1.0, v0.2.0 and v0.3.0 were each already force-moved off an inherited tag onto the merged line, so this is an established pattern here rather than a new one.

2. Test

362 tests pass, and the suite is genuine rather than decorative. What it does not cover is the thing most likely to be wrong:

• No consumer has been built against a published tag. Every consumer resolves this package through the sibling path locally, which compiles local working state rather than any release (ecosystem#48). A green fleet is therefore not evidence that 0.3.0 works for anyone off-machine. Worth building at least OCCTSwiftUX and OCCTMCP against the URL, in a clean checkout, before freezing.
• No multi-body file fixture exists. Both camera-framing regressions had to assert the bounds union directly, because the wiring from a real multibody import through to the framing cannot be exercised without one. That gap is now load-bearing in two repos.

3. Verify the deduplication

The audit behind #12 was a static read of every collision ecosystem#43 enumerated, and it came back clean apart from Axis. It was not a behavioural comparison. Before 1.0.0 it is worth confirming by execution rather than by reading, particularly:

• that OCCTSwiftAIS.InteractiveContext.resolve*SubShape and SubShapePickResolver cannot disagree, since the wrappers add mode gating and the whole-body fallback on top;
• that CADKit's façade over InteractiveContext has no path where the two selections can drift apart, which was the original CADKit adopts AIS selection state instead of running a parallel one #3 defect.

4. Comments

Scripts/comment-ratio-check.sh is report-only and currently flags 7 files at or above 1.0x comment:code:

File	comment	code	ratio
OCCTSwiftTools/FaceIdentityTable.swift	70	16	4.38
OCCTSwiftAIS/CompatibilityAliases.swift	14	4	3.50
OCCTSwiftTools/ShapeIdentity.swift	122	40	3.05
OCCTSwiftTools/EdgeIdentityTable.swift	38	16	2.38
OCCTSwiftTools/VertexIdentityTable.swift	36	16	2.25
OCCTSwiftTools/SubShapePickResolver.swift	98	56	1.75
OCCTSwiftTools/PointConverter.swift	32	26	1.23

Not all of these are wrong. SubShapePickResolver and ShapeIdentity are where the identity semantics are recorded, and that reasoning is expensive to reconstruct. The three identity tables at 2.2x to 4.4x over 16 lines of code each are the ones to look at: three near-identical files carrying three near-identical explanations is a sign the explanation belongs in one place they all point at.

5. Code style and structure

swift-format lint --strict and swiftlint --strict are both clean, so style in the narrow sense is fine. Structure is not.

2497  OCCTSwiftCADKit/CADViewportService.swift
 648  OCCTSwiftTools/CADFileLoader.swift
 581  OCCTSwiftAIS/InteractiveContext.swift
 543  OCCTSwiftAIS/ManipulatorWidget.swift

CADViewportService.swift is 2,497 lines, 30% of the package's 8,439, and holds loading, entities, selection, picking, clipping, capping, comparison, scalar fields, overlays and camera framing. It is the file every one of this session's changes had to touch, and the file where the camera bug survived a previous fix because the earlier pass could not see the whole of it.

The code-structure policy (the sixth mandatory OKF policy, August 2026) calls for one type per file with scoped remediation, modeled on OCCTSwift#377/#381. This is the repo's largest outstanding violation and the best argument for doing it before 1.0.0 rather than after: splitting a file is source-compatible, and doing it later means doing it against a frozen public surface.

ScalarField.swift carries 5 types and is the only other file over 3.

[gsdali]

Progress update. Item 2 (consumer testing) is now essentially done, as a side effect of the fleet moving to URL-only dependency resolution (ecosystem#51).

Every consumer now resolves this package by URL rather than through a sibling checkout, so the fleet's own CI is the consumer test this issue asked for:

Consumer	Pins Interaction	tests CI
OCCTMCP	0.2.0	success, 219 tests, Linux, no siblings
OCCTSwiftScripts	0.2.0	success
OCCTSwiftUX	0.2.0	85 tests locally; CI billing-blocked (private)

Two public consumers build and test against the published v0.2.0 tag on every push. That is the property that was missing when this was filed.

Also landed since: this repo's own manifest is URL-only (c3ae328), so the sibling probe is gone from it too.

Current state of main (c3ae328): 362 tests in 32 suites pass, swift-format lint --strict clean, swiftlint --strict clean.

What is still open

1. Tag namespace. Unchanged and still blocking: 26 inherited tags occupy v1.0.0 to v1.6.4, v1.0.0 is a May 2026 OCCTSwiftTools commit, and v0.3.0 is still an inherited tag rather than the release. Needs a decision, delete the inherited tags or start the stable line at 2.0.0.
2. Structure. CADViewportService.swift is 2,497 lines, 30% of the package's 8,439. It already carries 17 // MARK: - sections and several are 150 to 560 lines each (Selection 557, Clipping 326, Multi-body 315, Comparison 251), so the split is mechanical: one extension file per domain, stored properties staying in the core file. Source-compatible, no API change, and much cheaper before a frozen public surface than after.
3. Comments. Still 7 files at or above 1.0x. The three identity tables (Face 4.38x, Edge 2.38x, Vertex 2.25x, ~16 lines of code each) carry three near-identical explanations, which is one explanation in the wrong place rather than three files that are over-commented.
4. Dedup by execution. The Record the duplication audit, and stop describing settled work as open #12 audit was a static read. Still worth a behavioural pass confirming InteractiveContext.resolve*SubShape cannot disagree with SubShapePickResolver, and that CADKit's façade has no path where the two selections drift.
5. Multibody fixture. Still absent, which is why both camera-framing regressions assert the bounds union rather than a real import.

New, not in the original list

The deprecated surface would freeze into 1.0.0. Five deprecated declarations are currently public: SelectionSummary (typealias for SelectionMeasurements), selectionSummary, loadedShape, loadShape(_:id:) and selected. A 1.0.0 that ships them owes them support for the whole 1.x line. Worth deciding deliberately whether they survive the version boundary or are removed while removal is still free.

Public surface for reference: OCCTSwiftTools 56 declarations, OCCTSwiftAIS 170, OCCTSwiftCADKit 173.

[gsdali]

All four items are done, and v2.0.0-rc1 is cut (#14, merged as e00f7ba).

The stable line starts at 2.0.0, above the highest inherited tag, so item 1 needs no tag deletion. Nothing is removed from the namespace; v2.0.0-rc1 simply sits above v1.6.4.

Item	Outcome
1. Tag namespace	resolved by starting at 2.0.0; no deletions
2. Consumer testing	closed earlier by the URL-only change; OCCTMCP and OCCTSwiftScripts build against the published package in CI
3. Dedup verification	now by execution, not by reading the call graph
4. Comments	the missing cookbook page written; FaceIdentityTable 4.38x to 2.69x
5. Structure	2,306-line file becomes a 365-line core plus seven domain files
Deprecated surface	ten declarations removed, plus the machinery backing them

363 tests in 33 suites, both linters clean. Verified that a real consumer resolves and builds against the tag, not just resolves: that distinction has bitten this fleet before.

Two things worth recording

A test that passed without earning it. The first version of the resolver-agreement tests compared a single pick on triangle 0. They all passed with triangleIndex + 1 injected into the AIS wrapper, because a box puts two triangles on every face, so an off-by-one lands on the same face. They now sweep every primitive, and the same injection fails with six issues.

A correction to this issue. I recorded the three identity tables as carrying "three near-identical explanations". That was wrong: each carries its own genuine difference. What was duplicated was the shared reasoning underneath, which now lives in one cookbook page all three point at, a page the code already referenced but which did not exist.

What is left before 2.0.0 final

• Point a consumer at the rc. That is what an rc is for, and it is the only thing the work above cannot self-certify against a release that removes ten public declarations.
• No multibody fixture. Still why both camera-framing regressions assert a bounds union rather than a real import.
• CompatibilityAliases.swift. Three source-compat shims from the three-repo merge, deliberately never deprecated because a same-module typealias would warn at ~75 internal uses. Whether they belong in a stable release is a call I have not made.

Leaving this open until 2.0.0 final.