I'm completely content with that deal. But the deal only works if the warranty is clear. Unless it's unmistakable to users that they have crossed the line, they will complain if you break them. A comment next to the member is not enough: IDEs will happily auto-complete the names of internal-only members.

I think what I really want is some sort of access control for references to an object.

Like the default is the compiler will throw a warning if you access a private field with a default reference.

So things like this works but the compiler bitches.

   printf("what hell is bar doing %i", foo.bar);  // throws a warning 'bar is private'

But you can have a reference that's all in for api functions.

And also a reference that will throw a warning for any attempt access fields. The idea being it's a pure handle.

With private fields, there's a clear signal that you will be crossing a line by doing all those shenanigans -- like a 'no running' sign at the pool, you violate the rule and you accept responsibility for what happens next. With only public fields, there is no way to signal a rule. The pool no running sign is taken down.

And, there are valid reasons for a library writer to want to warn people off using certain fields, but still have them in-structure. Work-in-progress, internal machinery that the writer may wish to refactor at their leisure, whatever.

You could write that warning up in the documentation, but it's probably better as a structural affordance in the code, because then it's not just enforceable, but also lends itself to automation.