refactor: adopt cpmux conventions and clarify OPF ownership

[gugarosa]

Scope

Follow-up to merged/released #60. This keeps the agreed ownership, contract, internal-reuse, and cpmux-derived convention changes in one PR. It does not merge itself or publish another release.

Conventions and documentation

• Add CONVENTIONS.md and repository Copilot instructions based on the supplied cpmux rules.
• Apply the two-line Apache copyright/license header to all 75 Python files, modern union/builtin-generic annotations, collections.abc callables, absolute grouped imports, double quotes, and 120-column formatting.
• Restore useful Google-style public/constructor contracts, remove private-helper docstrings, preserve scientific references, and retain meaningful phase separators and why-only comments.
• Match cpmux/Black's one-line short summaries; multiline Google docstrings keep a blank line before the closing quotes and all docstrings keep the following statement separated.
• Standardize raised errors and warning/error diagnostics without changing the custom exception hierarchy or rewriting caller-supplied exception arguments.
• Restore constructor rendering, pip/editable installation instructions, and an executable usage guide covering mutation, indexing, lifecycle, persistence, and logging.
• Run existing quality hooks and strict HTML/doctest builds in CI. No new framework or lint-tool dependency is introduced.

Ownership and internal reuse

• Make numerical epsilon preparation non-mutating for arrays, views, aliases, and read-only inputs.
• Give named metric selection one owner so changing distance updates its registered callable atomically, while explicit custom callables remain supported.
• Isolate seeded split randomness with local RandomState, preserving historical permutations without reseeding application-wide state.
• Make logger configuration idempotent and preserve existing application configuration, retaining stdout/delayed rotating-file defaults for unconfigured loggers.
• Share the KNN prediction and minimax forest-growth operations in a narrow private module. Keep public model classes, runtime arguments/defaults, list/tuple/None returns, heap ties, matrix orientation, and semi-supervised label propagation.
• Separate internal KNN validation prediction from the public fitted-state check, and keep expected JSON read/decode sentinels while propagating unexpected failures.

Deliberate adaptations

OPFython retains Apache-2.0, its existing opfython.utils.logging module and public reexports, and Python >=3.11. The requested modern annotation idioms are compatible with 3.11. cpmux's MIT license, Textual/Typer/Pydantic architecture, empty-package-initializer rule, and interpreter floor are not transplanted. Package version and dependency versions remain unchanged.

Validation

• Baseline: 274 tests passed before edits.
• Final complete suite: 498 passed on each of Python 3.11, 3.12, and 3.13.
• The complete 498-test suite passed separately against isolated wheel and source-distribution installations, with archive provenance verified.
• All four fitted model families loaded pickles produced by the released 2.0.1 wheel with unchanged saved state and predictions.
• Public runtime arguments/defaults and class bases remain unchanged across all 27 existing package modules.
• All configured quality hooks pass, and structural convention checks cover all 75 Python files.
• Strict Sphinx HTML generation succeeds and all four executable usage blocks pass.

A numerical-guard microbenchmark used seven interleaved repeats of 5,000 calls on positive float64 vectors of 2, 32, and 512 features. New median times were 1.850-3.357 microseconds versus 1.964-3.743 for the equivalent copy-wrapped released implementation. The unsafe mutation-based implementation measured 1.473-2.932 microseconds. Variability was material; this is an allocation/correctness trade-off, not an application-wide speedup claim.