DISCUSS: Settle the private-module convention for subpackages

The decision needed

The _module.py private-plus-public-shim convention was applied to 21 of 23 top-level modules and to zero subpackage modules. A contributor cannot infer from the layout whether quantecon.markov.core is a supported import path or an implementation detail.

quad.py is the sharpest illustration: at 1,230 lines it is the single largest module in the package, fully public with no shim, directly contradicting the pattern applied to its 21 smaller neighbours.

Questions for the team

1. Is quantecon.markov.core a supported import path or an implementation detail?
2. Was the December 2022 conversion intended to reach the subpackages, or was the top level always the whole scope?
3. Do distributions and quad join the converted set, or are they deliberately public?
4. Is markov/_ddp_linprog_simplex.py correctly private, or accidentally so?

This needs a written decision more than it needs code — recording it in the contributing guide is worth more than any refactor; the current state is not wrong so much as unstated. If the answer is "finish the convention", the execution should be a separate refactor issue and should land alongside the shim removal decided in #865, so users absorb one round of import churn rather than two. Close this thread with a summarised decision and spawn the concrete follow-up.

From the July 2026 technical-debt audit (AI-assisted; claims verified against 28d4b3b on 2026-07-25).

Review the listed top-level and subpackage module conventions, the contributing guide, and the shim-removal context in #865. Capture the team’s decision about supported import paths and private modules in the contributing guide, summarize it on this issue, and open a separate follow-up for any refactor.