refactor!: clarify planner realization, schema, and handoff APIs

[zzylol]

Why

Closes #427. Planner APIs reused “implementation,” “bind,” and “boundary” for unrelated concepts, making candidate construction, schema resolution, window coverage, and physical transfers hard to distinguish.

What

Rename the concepts and their callers consistently:

• Realization, RealizationError, and SummaryRealization identify candidate physical forms; internal enumeration becomes realizations_for_intent.
• SchemaResolver::resolve_schema and resolve_schema_with_inherited replace the schema binder family.
• PaneLayout and WindowEdgeCoverage::ExactWindowEdgeResidual describe window coverage.
• physical_handoff_cost, PhysicalHandoffKind, PhysicalHandoffBytes, and the related evidence/profile/estimate types describe transfers and materialization.
• Internal CandidatePlanningInputs and new_with_planning_inputs* constructors name injected cost, accuracy, allocation, and evidence dependencies.

Update documentation to use “comparison scope” and “planner-runtime contract,” including document paths and incoming links. Ordinary fluent builders and SQL/PromQL syntax retain their names.

Renaming and refactor map

Previous name	Current name
replacement::Implementation	replacement::Realization
replacement::ImplementError	replacement::RealizationError
ReplacementProvenance::SummaryImplementation	ReplacementProvenance::SummaryRealization
implementations_for_with (internal)	realizations_for_intent
pre_asap::binder	pre_asap::schema_resolver
Binder	SchemaResolver
Binder::bind	SchemaResolver::resolve_schema
Binder::bind_with_inherited	SchemaResolver::resolve_schema_with_inherited
PanePhaseBinding	PaneLayout
BoundaryCoverage	WindowEdgeCoverage
ExactBoundaryResidual	ExactWindowEdgeResidual
WindowEdgeCompatibility::RequiresAlignedPanePhaseOrExactBoundaryResidual	WindowEdgeCompatibility::RequiresAlignedPanePhaseOrExactWindowEdgeResidual
resources::boundary	resources::physical_handoff
BoundaryKind	PhysicalHandoffKind
BoundaryResources	PhysicalHandoffBytes
asap_aware_mapping::boundary_cost	asap_aware_mapping::physical_handoff_cost
PhysicalBoundary	PhysicalHandoff
BoundaryNodeEvidence, BoundaryPlanEvidence	PhysicalHandoffNodeEvidence, PhysicalHandoffPlanEvidence
BoundaryProfile, BoundaryCalibration, BoundaryEstimate	PhysicalHandoffProfile, PhysicalHandoffCalibration, PhysicalHandoffEstimate
BOUNDARY_MODEL_VERSION	PHYSICAL_HANDOFF_MODEL_VERSION
estimate_boundaries	estimate_physical_handoffs
Physical evidence/comparison boundaries fields	handoffs
BoundaryEstimate::per_boundary	PhysicalHandoffEstimate::per_handoff
Internal Models	CandidatePlanningInputs
SketchAlgorithmStrategy::with_models	SketchAlgorithmStrategy::new_with_planning_inputs
SketchAlgorithmStrategy::with_models_and_evidence	SketchAlgorithmStrategy::new_with_planning_inputs_and_evidence
HydraGroupingStrategy::with_models_and_evidence	HydraGroupingStrategy::new_with_planning_inputs_and_evidence
“comparison boundary” (documentation)	“comparison scope”
Downstream “boundary” (documentation)	“planner-runtime contract”
physical-boundary-costs.md	physical-handoff-costs.md
planner-downstream-boundary.md	planner-runtime-contract.md

These are Rust source/API and documentation renames. Serialized keys, variant values, resource labels, and model-version strings retain their existing names for compatibility.

How

This is a source API refactor with no new planning abstraction or algorithm. All workspace consumers use the new vocabulary. Explicit Serde names preserve deployed JSON keys and variants; model-version strings and exported resource labels remain stable.

Before this PR

A caller used Binder::new().bind(&tree), cost-model extensions returned Implementation, and a physical transfer used BoundaryKind even though pane coverage also used “boundary.”

After this PR

The same caller uses SchemaResolver::new().resolve_schema(&tree), returns Realization, and declares a PhysicalHandoffKind. Window edges use WindowEdgeCoverage. The same queries and physical evidence produce the same plans and resource arithmetic.

See the migration guide for the complete source-name mapping.

Evidence

• Full workspace run: 1,166 passed, 0 failed, 0 ignored across 66 test/doc-test suites.
• New external-style API tests exercise schema resolution and physical handoff imports, and preserve existing window-edge wire values.
• Handoff evidence/estimate tests preserve boundaries and per_boundary JSON keys and the expected 240-byte network estimate.
• The existing planner-cost export test now also checks the original nested boundaries keys before parsing and selecting a physical plan.
• Screenshots, performance measurements, and architecture diagrams: not applicable to this naming refactor.

Verification

• cargo test --workspace --locked: passed.
• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings: passed.
• cargo fmt --all --check and git diff --check: passed.
• bash tools/verify_metricsql_external_consumer.sh: passed on stable Rust.
• python3 tools/verify_metricsql_vendored_baseline.py: passed; preserved the 21 library and 3 documentation upstream failures recorded by that baseline checker.
• Rustdoc for asap-types and asap-aware-mapping: built successfully; existing documentation warnings remain. Relative links in changed Markdown documents resolve.

Architectural decisions

Use one Rust naming family per concept rather than retain old aliases alongside it. Migration notes cover the source break. Preserve wire names through Serde so downstream evidence files and exported contracts require no JSON migration.

Limitations and follow-up

This breaks Rust source imports and call sites using the old names; downstream crates must apply the migration table. Historical archived documentation is unchanged. This is implementation and verification by the same agent, not an independent review.

Human review — do not complete with an agent

• The MVP boundary is correct.
• New conceptual layers or public interfaces are necessary.
• The before/after description matches the intended product behavior.
• Human reviewer:
• Decision and rationale: