Future State Proposals

Tags contributor architecture

These documents describe the intended end state for high-impact cleanup and refactoring TODOs. Each proposal is tied to a planning item under _project/TODO/main/planning/ and makes the destination architecture explicit: what gets pruned, excluded from the wheel, or reorganized within BenchBox.

Sequencing and Priority

Not all proposals should be pursued simultaneously. Adversarial review established the following priority tiers based on coupling analysis, effort, and evidence of need:

Tier 1: Act now (small effort, clear value):

  • artifactlinks: Completed in v0.2.1 — the old generic publishing layer was pruned. benchbox/core/publishing/ now hosts the live, CLI-integrated bundle-publish subsystem; do not prune it. See Prune publishing.

  • benchbox-maintainer: Near-zero coupling. Remove entry point and exclude from wheel.

  • benchbox-experimental: Namespace hygiene for 5 misplaced subsystems.

Tier 2: Act when prerequisites are met:

  • Benchmark family plugin seam: Classify benchmark APIs and pilot a small family interface before splitting core benchmark packages.

  • MCP APIs: Already an optional extra. Formalize 3 internal API refs as public exports. Defer distribution split until post-v1.0.

  • Monitoring: Light coupling but no second consumer. Gate behind benchbox[monitoring] optional extra first.

Two proposals were discarded during adversarial review:

  • sqlplankit (query-plan extraction): 37-file blast radius, shared-type boundary problem (QueryPlanDAG embedded in core result model), no external demand. Internal boundary improvements can be done without a package split.

  • todo-dag: _project/ does not ship to users, no second consumer exists. Extracting a package for single-repo contributor tooling is package sprawl.

Proposals