Drop the _allocation suffix from the public functions

[fpedd]

Four public names carry an _allocation suffix that repeats what the package
name and the argument already say:

om.validate_allocation(pool)
om.plot_allocation(pool)
om.io.save_allocation(pool, path)
om.io.load_allocation(path)

The suffix is not descriptive. It exists because validate.py and
visualize.py are modules, so importing from them in __init__.py binds the
module as a package attribute and takes the short name. om.validate today is
a module, and om.validate(pool) raises TypeError: 'module' object is not callable.

_allocate.py already solves this: the module is private, so allocate is
free to be the function.

Proposal

Module	New name
omnimalloc/validate.py	omnimalloc/_validate.py
omnimalloc/visualize.py	omnimalloc/_visualize.py
omnimalloc/io.py	unchanged

Now	Proposed
om.validate_allocation(entity)	om.validate(entity)
om.plot_allocation(entity, path)	om.plot(entity, path)
om.io.save_allocation(entity, path)	om.io.save(entity, path)
om.io.load_allocation(path)	om.io.load(path)

io.py stays public

The first draft of this issue proposed _io.py re-exported as io. That is
wrong on both halves.

It is unnecessary: the suffix problem comes from __init__.py importing the
module, and __init__.py never imported .io — #49 removed save_allocation
and load_allocation from the top level. Nothing shadows the short names
there.

It is also breaking. from omnimalloc.io import load resolves a real
submodule, not a package attribute, so from . import _io as io would raise
ModuleNotFoundError for every caller using that spelling, including
benchmark/sources/minimalloc.py.

Instead __init__.py imports the module, so om.io resolves after a plain
import omnimalloc, and all three spellings work:

om.io.save(pool, path)                  # via the package attribute
from omnimalloc.io import save, load    # via the submodule
import omnimalloc.io                    # directly

Resulting top level, nine names (#49 already established the other eight;
this issue renames two of them and adds io):

__all__ = [
    "Allocation", "Memory", "Pool", "System",
    "__version__", "allocate", "io", "plot", "validate",
]

The rename is not purely mechanical

Three call sites take a validate: bool parameter and call the validator in
the body, so a plain find-and-replace makes the parameter shadow the function
and the call site invokes a bool:

• _allocate.allocate
• benchmark._benchmark_result
• scripts/generate_readme_assets._solve

All three alias the import (from ._validate import validate as _validate).
ty catches the miss as call-non-callable, which is how the third one
surfaced — it is not reachable from the test suite.

Two more spots a mechanical sweep misses:

• LANE_CAVEAT and PANEL_CAVEAT in _visualize.py embed
  validate_allocation() in a string that is rendered as the figure
  suptitle. They now read omnimalloc.validate(), qualified, because a bare
  validate() in a figure caption says nothing.
• CLAUDE.md names all four functions and is untracked, so it appears in no
  diff and no git grep.

Scope

Occurrence counts on main (88f8303):

Name	Files	Occurrences
validate_allocation	33	171
plot_allocation	12	45
save_allocation	2	21
load_allocation	3	14

One module import needs redirecting: tests/unit/test_visualize.py does
from omnimalloc import visualize and monkeypatches through it; it now
monkeypatches by dotted path instead.

Follow-on cleanups

The rename establishes one rule — the module is an implementation detail, the
package __init__ is the API — and the same rule applies in four more places.
Each is a separate commit.

1. __all__ in every package. Shrink the top-level namespace to eight names #49 gave the top level an __all__; the
   eight subpackage __init__ files still use from .x import Y as Y. Two
   spellings for one job. Also surfaced two gaps where omnimalloc.benchmark
   did not mirror omnimalloc.benchmark.sources: SkewedSource,
   TwoPlusTwoSource, SIZE_DISTRIBUTIONS, sample_sizes.

2. analysis/ speaks one dialect. _conflicts.py and _pressure.py were
   private, clock.py and linearize.py were not. clock.py was the only
   module the package did not re-export, so seven modules across four packages
   reached past __init__ for time_components and uniform_dim. Both are
   now exported; the modules become _clock.py and _linearize.py.

   This surfaced a latent import cycle. primitives/pool.py bound
   analysis._pressure at module scope for Pool.pressure — the one upward
   reference in the layering — while analysis imports primitives. Nothing
   broke only because _conflicts happened to sort first in the __init__ and
   pulled primitives in before _clock ran. Putting _clock first closed
   analysis -> _clock -> primitives -> pool -> _pressure -> _clock on a
   half-initialized module. The upward reference is now deferred into
   Pool.pressure, so no import order can close it.

3. _benchmark is the same suffix. run_benchmark/plot_benchmark/
   save_benchmark become om.benchmark.run/.plot/.save, and
   benchmark/benchmark.py and results/visualize.py become _benchmark.py
   and _visualize.py. Timer joins the exports — four scripts imported it
   from omnimalloc.benchmark.timer, the same reach-past-__init__ that
   clock.py invited.

4. benchmark no longer imports the root package. benchmark/benchmark.py
   did from omnimalloc import allocate, validate_allocation, the one import
   that made a subpackage depend on the package __init__. Folded into the
   rename commit since the names change there anyway.

Considered and dropped

• Normalizing absolute vs relative imports. The 135/168 split is not drift:
  ruff runs select = ["ALL"], so TID252 is active with
  ban-relative-imports = "parents". The rule is already enforced — . for
  same-package siblings, absolute where .. would be needed.
• common -> _common. common/__init__.py is empty, so nothing leaks and
  the change is cosmetic. It would touch ~30 files and conflict with all five
  open PRs. Worth doing when the queue drains, not now.

Notes

No deprecation aliases. The project is pre-1.0 and there are no external
consumers to carry.

[fpedd]

The public API surface, after this issue

Every name reachable without touching an underscore, enumerated by importing
each package and reading its __all__. 115 exported names across 9
namespaces, 9 of them at the top level.

Entity below is shorthand for System | Memory | Pool | Sequence[Allocation],
which every entry point accepts.

omnimalloc — 9

Name	Signature
Allocation	(id, size, start, end, offset=None, kind=None) — C++ class
Memory	(id, pools, size=None)
Pool	(id, allocations, offset=None)
System	(id, memories)
__version__	str
allocate	(entity: Entity, allocator=None, validate=False) → same type in, same type out
io	submodule, below
plot	(entity, path=None, capacities=None, view="panel", max_lanes=None) -> None
validate	(entity, require_capacity=False, alignment=None) -> None

omnimalloc.primitives — 8

Allocation, AllocationKind, Memory, Pool, System, VectorClock,
and the two aliases IdType = int | str, TimePoint = int | tuple[int, ...].

omnimalloc.analysis — 15

The nine-query family, plus the conflict graph and the two clock helpers that
this issue promoted out of clock.py.

Name	Returns	Budget kwarg
conflicts	dict[IdType, set[IdType]]	work_budget=10_000_000
conflict_degrees	list[int]	work_budget=10_000_000_000
conflict_graph	ConflictGraph	work_budget=1e10, max_entries=None
ConflictGraph	C++ class	—
pressure / pressure_per_allocation	int / dict	work_budget=100_000_000
antichain_pressure / …_per_allocation	int / dict	work_budget=100_000_000
closure_pressure / …_per_allocation	int / dict	closure_cap=16384
placement_pressure	int	—
placement_pressure_per_allocation	dict	work_budget=1e10
try_linearize	tuple[Allocation, ...] | None	work_budget=1e10
time_components	tuple[int, ...]	—
uniform_dim	int	—

omnimalloc.allocators — 22

BaseAllocator, available_allocators(), DEFAULT_ALLOCATOR = "omni", and 19
allocators:

• no config: NaiveAllocator, BestFitAllocator, GreedyAllocator +
  ByArea / ByConflict / ByConflictSize / ByDuration / BySize / ByStart
• GreedyByAllAllocator(num_threads=None)
• OmniAllocator(linearize_budget=1e10)
• RandomAllocator(num_trials=100, seed=42)
• SupermallocAllocator(timeout=3.0, heuristics=…, num_threads=None)
• MinimallocAllocator(timeout=3.0, capacity=1TiB)
• TelamallocAllocator(seed=42, max_backtracks=10000, timeout=3.0)
• GeneticAllocator(…7 kwargs), HillClimbAllocator(…4),
  SimulatedAnnealingAllocator(…5), TabuSearchAllocator(…5)

Worth noting: CLAUDE.md documents a Sweep family (SweepAllocator,
HybridSweepAllocator, SweepByAllAllocator, …) and a NeuralAllocator.
Neither is in the shipped registry on main — the docs describe branches that
have not landed. Separate issue, but the API enumeration is the place it shows
up.

omnimalloc.io — 2

Name	Signature
save	(entity: Entity, path) -> tuple[Path, ...]
load	(path) -> Pool

omnimalloc.benchmark — 27

• entry points: run(...), plot(artifact, path=None), save(campaign, …)
• artifacts: BenchmarkResult, BenchmarkReport, BenchmarkCampaign
• Timer, BaseSource, available_sources(), DEFAULT_SOURCE = "random",
  SYNC_PATTERNS (11), SIZE_DISTRIBUTIONS (5), sample_sizes(...)
• 14 sources: Random, Sequential, Uniform, HighContention, PowerOf2,
  Tiling, ConcurrentTiling, Pinwheel, SyncPattern, Skewed,
  TwoPlusTwo, Huggingface, Minimalloc + MinimallocSubset

omnimalloc.benchmark.sources — 20, .results — 5, .converters — 7

sources and results are strict subsets of what benchmark re-exports.
converters is not re-exported anywhere: Buffer, Model, Op, from_onnx,
model_to_allocations, model_to_pools, model_to_system.

Deliberately not public

omnimalloc._cpp (26 names — the placement kernels, analysis kernels, and
Partition/Solution/FirstFitPlacer), omnimalloc.common.* (constants,
deadline, parallel, registry, validation, directories), and the private modules
_allocate, _validate, _visualize, analysis/_*, benchmark/_benchmark,
benchmark/results/_visualize.

Two open questions

1. omnimalloc.common is neither public nor private. common/__init__.py
   is empty, so nothing is exported, yet common.constants and
   common.directories are reached by absolute path from scripts. _common
   would say what is true. Deferred here only because it touches ~30 files and
   conflicts with every open PR.

2. max_threads / set_max_threads have no public home. They are
   process-global knobs living at omnimalloc.common.parallel. If they are
   meant for users they belong at the top level; if not, _common covers them.
   Relevant to whichever branch lands the thread-cap work.