chore(#513, #667): build the Cluster D continuity census

[gsdali]

What & why

Cluster D of the v2.0.0 release (#667). #513 already wrote the continuity-handling
census as prose: 38 unaudited bridge functions, four incompatible request
encodings, two live defects. This PR turns that into a committed, executable
artifact that measures the current tree, per #667's own instruction ("#513 is
already an explicit census... Do the census, then the instances fall out").

This PR is the census only. It does not fix #437, #438, or
BRepGraph.edgeMaxContinuity's stub.

What's here

• Scripts/repro/censuses/ClusterD.swift (dynamic, primary evidence, swift run Censuses cluster-d): 31 distinct entry points measured against real fixtures.
• Scripts/repro/cluster-d-continuity/classify_continuity_sites.py (static
  cross-check): classifies 42 named bridge functions by which of the three
  shared occtGeomAbsFrom* decoders (Consolidate the bridge's ~8 duplicate int→GeomAbs_Shape continuity mappers — divergent numbering already shipped one bug (#433) and still causes bsplineRestriction vs bsplineRestrictionAdvanced to silently disagree #490) each calls, or none. 13/13 self-test
  cases pass, each with a proven guard-removal pair.
• Scripts/repro/cluster-d-continuity/README.md: full write-up.
• One line in CensusRunner.swift registering cluster-d.

Headline findings

• Continuity handling census across the kernel and the bridge: 38 unaudited functions, four incompatible request encodings, two live defects #513's own numbers were already stale when read against the current tree.
  Two of its named "live defects" (FilletBuilder.setContinuity's raw cast,
  OCCTThruSectionsSetContinuity's old reading) were fixed as part of Consolidate the bridge's ~8 duplicate int→GeomAbs_Shape continuity mappers — divergent numbering already shipped one bug (#433) and still causes bsplineRestriction vs bsplineRestrictionAdvanced to silently disagree #490's own
  PR, which cites Continuity handling census across the kernel and the bridge: 38 unaudited functions, four incompatible request encodings, two live defects #513 by number in its source comments. The one still open:
  BRepGraph.edgeMaxContinuity is confirmed (not assumed) to be a hardcoded
  stub always returning 0, contrasted against Shape.maxContinuity(edge:)
  reporting the real class on the same cylinder.
• Measured today: three canonical decoders (post-Consolidate the bridge's ~8 duplicate int→GeomAbs_Shape continuity mappers — divergent numbering already shipped one bug (#433) and still causes bsplineRestriction vs bsplineRestrictionAdvanced to silently disagree #490), not "four incompatible
  encodings." Plus two structurally different raw pass-throughs (the
  knot-splitting family's literal derivative order, ruled non-decodable by Surface/LawFunction knot splitting kept the continuity cap of 2 that #398 proved is a no-op #480;
  the plate family's literal GeomPlate order, undocumented until now).
• A second #438-shaped duplicate, found beyond Continuity handling census across the kernel and the bridge: 38 unaudited functions, four incompatible request encodings, two live defects #513's own list:
  Surface.splitByContinuity and Surface.splitSurfaceByContinuity are two
  public APIs over the same ShapeUpgrade_SplitSurfaceContinuity -- confirmed
  now converged (Consolidate the bridge's ~8 duplicate int→GeomAbs_Shape continuity mappers — divergent numbering already shipped one bug (#433) and still causes bsplineRestriction vs bsplineRestrictionAdvanced to silently disagree #490), not diverged.
• Shape.plateSurface(through:orders:) can never accept .g2: one curvature point fails the whole call #437 reproduced directly: a .g2 point constraint fails
  plateSurface(through:orders:) every time; curve constraints don't have the
  same restriction. Confirmed as a raw pass-through into
  GeomPlate_PointConstraint's own literal order, not a decode bug.
• Shape.plateSurface(through:orders:) can never accept .g2: one curvature point fails the whole call #437 and divided(at:) and dividedByContinuity(criterion:tolerance:) are two public APIs over one OCCT class #438 are NOT the same defect, correcting Cluster D: four incompatible continuity encodings across 38 functions #667's framing. Shape.plateSurface(through:orders:) can never accept .g2: one curvature point fails the whole call #437 is
  a genuine instance of the shared "four encodings" root (a raw pass-through
  hitting a real OCCT domain restriction). divided(at:) and dividedByContinuity(criterion:tolerance:) are two public APIs over one OCCT class #438 is independent: both
  divided(at:)/dividedByContinuity correctly decode through the same
  canonical decoder; they diverge because they set different criteria on the
  underlying builder, an API-surface duplication question, not an encoding one.
• A genuine, honestly-reported open question: Shape.continuity(edge:...)
  (BRep_Tool, unmigrated) disagrees with continuityClassOfFaces (BRepLib,
  migrated by Bridge's GeomAbs_Shape ordinal vocabulary for continuity is hand-copied into three divergent C++ conversion helpers (orderToShape/shapeToOrder ×2, continuityFromInt78) and four drifted header comments, never wired to the canonical Surface.Continuity enum #398/PR#436 established #495) on a cylinder's seam edge (0 vs cN). The first hypothesis
  tried (a cached-flag vs live-computation gap) was tested directly with
  encodingRegularity() and disproved. A narrower, unconfirmed mechanism is
  recorded in the README rather than a guess dressed as a finding.

Verdict on #513

Recommend closing once this merges: its own ask (turn the prose into an
executable artifact) is done, its live defects are one fixed / one tracked as a
small follow-up, and its remaining open decision (the null/failure sentinel
policy on the result side) is a design question better tracked on its own than
kept open against a census issue whose job is complete. Full reasoning in the
README's "Should #513 close?" section.

Verify

• Clean full-package build: 0 errors, 0 new warnings (only the pre-existing,
  deliberate ClusterA.swift deprecation warning).
• Full swift test: 5356/5356 passing, run twice for confirmation.
• swift run Censuses cluster-a: still 45 rows, unchanged logic.
• swift run Censuses cluster-b: still 16 rows, unchanged logic.
• All four gate scripts (check-bridge-index, check-null-handle-guards,
  check-docs-defaults, count-operations) plus their --self-tests: pass.
• classify_continuity_sites.py --self-test: 13/13, guard-removal matrix in
  the README.
• Zero em-dashes across all new/changed files.

Checklist

• New behavior (the census itself) is exercised via --self-test for the
  static classifier, with every case proven by removing the guard and
  watching the classification move, per
  okf/policies/prove-the-test-fails.md.

Notes for the reviewer

No files in this PR overlap with the two other PRs open against
refactor/381-pass1b at the time of writing (#711, Cluster C's
check-null-handle-guards.py upgrade; #712, ClusterB.swift/#633 fix) --
confirmed by diffing file lists before opening this PR.

Closes #513

[secondmouseAU-bot]

Review: chore(#513, #667): build the Cluster D continuity census

Overview

Turns the #513 continuity-handling census from prose into a committed, executable artifact: Scripts/repro/censuses/ClusterD.swift (dynamic, 31 measured entry points), classify_continuity_sites.py (static cross-check, 42 named bridge functions, 13/13 self-tests), a README write-up, and a one-line registration in CensusRunner.swift. No production code, no behavior fixes — the PR is explicit that #437, #438, and BRepGraph.edgeMaxContinuity's stub are out of scope. +1361/-0 across 4 files.

Verification

Per this repo's docs-currency convention, I didn't take the PR's claims on faith — I pulled the actual refactor/381-pass1b source and checked the two most load-bearing ones directly:

• OCCTBRepGraphEdgeMaxContinuity in OCCTBridge_BRepGraph.mm — confirmed byte-for-byte: int32_t OCCTBRepGraphEdgeMaxContinuity(OCCTBRepGraphRef, int32_t) { return 0; }.
• The three canonical decoders in OCCTBridge_Internal.h (occtGeomAbsFromSurfaceContinuity, occtGeomAbsFromParametricContinuity, occtGeomAbsFromAnalysisOrder) all exist, and their saturation behavior matches the README's table exactly (e.g. occtGeomAbsFromParametricContinuity's default: return level < 0 ? GeomAbs_C0 : GeomAbs_CN;).
• classify_continuity_sites.py's file constants match the real Sources/OCCTBridge/src/*.mm layout, and REPO_ROOT = Path(__file__).resolve().parents[3] is the correct depth from Scripts/repro/cluster-d-continuity/.
• The self-reported counts are internally consistent: 34 request-side + 8 result-side = 42 (matches the two Python lists exactly), and the totalMeasured increments in ClusterD.swift sum to exactly 31 along the code's happy path (matches the README's headline number).

This is a well-grounded audit, not just a plausible-sounding one.

Code quality & style

• Clear MARK-section structure that mirrors the README 1:1 — easy to cross-reference a table back to the code that produced it.
• Doc comments explain why a fixture was chosen (e.g. the sphere-vs-cylinder-vs-plane progression in clusterDRecordAnalysisOrderSaturation, picked because a cylinder's D2V is exactly zero) rather than just what — genuinely useful for whoever next needs to extend this.
• The Python classifier's self-test methodology (guard-present / guard-removed pairs proving the label actually moves) is a real strength — it's easy to write a static classifier that "passes" only because its fixtures already match the expected label, and this one guards against that.

Issues / suggestions

1. Two guard … return inside ClusterD.run()'s do blocks return from the whole function, not just that section. Section 3's fixture guard (the Wire.line boundary) and section 6's fixture guard (Shape.cylinder/BRepGraph) both return on failure — but do {} doesn't introduce a new function scope, so a failure there silently skips every remaining section, including the final summary in section 7. All fixtures are static/hand-built today so this shouldn't trigger, but if it ever does (e.g. after an OCCT upgrade changes a builder), the failure mode is a partially-run census that looks like a clean one except for one buried "could not build" line. Worth wrapping those two guards in a local closure, or switching to a non-fatal early-out, so a fixture failure degrades one section rather than the whole report.

2. The README's headline counts (31 / 42 / 34 / 8) are asserted in prose, not enforced in code. totalMeasured is computed and printed by ClusterD.swift, but nothing fails the build/test if a future edit changes that number without updating the README — which is the exact "prose census goes stale" failure mode this PR's own motivation calls out against Continuity handling census across the kernel and the bridge: 38 unaudited functions, four incompatible request encodings, two live defects #513. Given the self-test infrastructure already built for the Python side, a cheap follow-up would be an assertion (or CI grep) that the two stay in sync.

3. The edgeMaxContinuity finding slightly undersells what's actually in the source. The README frames it as "the live stub Continuity handling census across the kernel and the bridge: 38 unaudited functions, four incompatible request encodings, two live defects #513 flagged, still unfixed" and asks for the same - Important: doc-comment treatment as its sibling. Fair, but the comment immediately above the stub in OCCTBridge_BRepGraph.mm already explains why: BRepGraph_LayerRegularity is broken/uncompilable in OCCT 8.0.0p1, so "the graph path is unavailable" by upstream necessity, not neglect. Worth folding into the README/follow-up framing — "blocked on an upstream kernel bug" is a meaningfully different (and more useful) follow-up than "nobody's gotten to it yet," and since the PR says it read this exact file before writing the section, the omission reads as a miss rather than a deliberate simplification.

Test coverage

Appropriate for what this is. The static classifier has 13/13 self-tests with proven guard-removal pairs (genuinely tests the classifier's logic, not just its fixtures). The dynamic census isn't itself unit-tested, which is reasonable since it is the report — consistent with the Cluster A/B precedent it follows. swift test (5356/5356, run twice) and all four gate scripts are reported green in the PR description.

Performance & security

No production code touched — Scripts/repro/** is dev-only tooling. No untrusted input, no network access, and file access is confined to a fixed relative path under the repo root. Nothing to flag.

Verdict

Solid, well-verified audit work that does what it claims: measures the current tree instead of trusting #513's now-stale prose, and is honest about the one place (the cylinder-seam continuity disagreement) it couldn't fully close the loop. The control-flow nit (#1) and documentation-drift risk (#2) are minor and shouldn't block merge; #3 is worth a one-line README fix before or shortly after merging.

---

🤖 Reviewed with Claude Code