JVM-lineage visibility & transitivity — research notes for PROP-050

0. One-line orientation

02Four systems, four different answers to "who sees what, and how far does it travel". Only two of them (Swift package/@_spi, JPMS qualified exports) actually implement friendship; both are provider-declared. Our inversion (consumer-declared, budget-motivated) flips several lessons — flagged inline as [INVERSION].

1. JPMS

2. Sealed classes — the allowlist lesson

12Constraint that matters: "The sealed class and its permitted subclasses must belong to the same module, and, if declared in an unnamed module, to the same package" (JEP 409; Oracle). Enforced at compile time; the JVM re-checks PermittedSubclasses at load time. Motivation: a closed world the compiler can reason over (exhaustive switch), which is only sound if the whitelist is verifiable — hence the same-maintenance-domain rule.

13Lesson for a friends-allowlist: an allowlist is only trustworthy when the allowlist and its members share one maintenance domain, and there is an explicit, syntactically visible escape hatch (non-sealed) rather than silent widening. [INVERSION] Our friendship is consumer-declared at the root — that gives us the single maintenance domain for free (one file, one owner), which is strictly better than permits. The cost transfers to name stability: the root allowlists nodes it did not author, so package coordinates become load-bearing API. Mitigate: allowlist entries are matched against the resolved closure at install time, unmatched entries warn (JPMS qualified-export precedent), and a non-sealed-style per-node open marks a hole visibly.

3. Kotlin

15"Module" = "a set of Kotlin files compiled together": an IntelliJ module, a Maven project, a Gradle source set, an Ant task invocation (docs). This is the friction: the visibility boundary is not a declared entity — it is whatever the build tool happened to compile together, so it shifts when the build changes, and needs special cases (the test source set can see main's internal). Second friction: the JVM has no internal, so it compiles to public + name mangling (foo$module_name); Java callers can reach it, and public members of internal classes aren't mangled at all (Kotlin/Java interop, 4comprehension). Enforcement: compile-time only, advisory at the bytecode layer.

16Explicit API mode (explicitApi() / explicitApiWarning() / -Xexplicit-api={strict|warning}) forces explicit visibility modifiers and explicit return types on the public surface, production sources only (docs). It is the opt-in, per-project, warning-then-error ratchet JPMS never offered.

17COPY: Explicit API mode wholesale — a per-root explicit_visibility = warn|strict flag that requires every edge to state access instead of defaulting silently. That is how you flip a default without a flag day. AVOID: Kotlin's module definition. Bind visibility to the declared edge / package coordinate, never to "whatever landed in the same materialised lane" — an implicit compilation-unit boundary is exactly the mistake, and in our system the lane composition is itself the variable.

4. Swift — the closest match to our design

19The exact gap package filled: a helper module inside a multi-module package had to be public to be usable by its siblings, which also exposed it to the world — no level meant "shared within my group, invisible outside". Rejected alternatives are directly instructive: submodules (bakes structure into ABI), internal(PackageName) (too verbose/general), and named groups within a package — abandoned because it "would tend to lead to large, complex manifests mingling the details of all the layers." That is a direct warning against fine-grained per-edge friendship grants at the root.

20Enforcement: compile-time, by comparing the package-name string recorded in the built interface. Transitivity: none — package is a flat, symmetric, unordered group, not a graph relation.

21SE-0409 is the single closest precedent to our per-edge access: the consumer annotates its own import edge to control leakage to its own clients — dependency-creep control, i.e. our seepage control. Critically, its default is still public in Swift 5 and 6, with the flip to internal deferred to a future language mode. Apple, with full control of compiler and build tool, still refused the flag day.

22COPY: (a) SE-0409's per-edge, consumer-declared propagation control — that is our model, validated; (b) @_spi's bilateral handshake (provider names a group, consumer opts in by name) — it makes seepage impossible to acquire accidentally and gives both sides a veto; (c) packageAccess: false as the shape of exclude; (d) the staged default flip. AVOID: string-matched implicit groups (-package-name) — invisible in source, silently coupling; and heed the rejected-alternatives note: keep friendship grants coarse (named groups / roles), not per-edge pairs, or the root manifest becomes the "large, complex manifest mingling all the layers" Swift explicitly refused to build. [INVERSION] Since ours is budget control, not secrecy, the enforcement output should be a pruning report (what was excluded, tokens saved) rather than an error — Swift/JPMS can hard-fail because a missing symbol breaks the build; a missing prompt lane merely makes the agent dumber, so the failure must be made legible instead.