feat: add workload-level library integration API (#453)

[zzylol]

Why

Two requirements, split out of #423:

• [Design] Give lib User One Single lib-func Abstraction #429 — a library user has no one-call path. Embedding ASAPPlanner means assembling the pipeline stage by stage, and the only facade re-exporting more than one frontend is asap-devtools, a developer-tools crate.
• [Design] Support a Separate Optimization Pass Besides the Current One For Grey-Box Users #430 — optimization is a hard-coded two-phase pipeline, and every extension point sits inside it. An algorithm with no candidate-generation phase can only be added by disguising itself as a rule.

This PR also closes #453.

What

e2e_plan gives library users one call from a prepared workload to the selected Post-ASAP DAG for every query. OptimizationPass gives developers a replaceable optimization stage — not an interface users call, but the slot the stage sits in, with the shipped algorithm as one implementation.

Design doc: docs/design_docs/architecture/updated_interface_with_pluggable_optimization.md.

PlanSpace, cost_sorted, and global_selection are unchanged.

Before this PR

Planning one SQL workload with lifecycle decisions, from a PlanningWorkload and a catalog:

// 1. Lower every normalized entry, and record which entry each root came from.
//    Not lower_sql_batch: it walks query_batch alone and drops repeating entries.
let mut roots = Vec::new();
let mut entry_indices = Vec::new();
for (index, entry) in workload.query_workload.entries().enumerate() {
    let accuracy = entry.requirements.accuracy.target();
    let expr = lower_sql_dialect(&entry.query.0, &catalog, dialect.clone(), accuracy.clone()).await?;
    roots.push((index, Rc::new(expr), Some(accuracy)));
    entry_indices.push(index);
}

// 2. Search.
let strategies = default_strategies_with_evidence(&cost_model, &evidence);
let space = search_workload_with_targets(roots, &strategies, &accuracy_model);

// 3. Select once, re-binding roots to workload entries.
let demand = WorkloadDemand {
    workload: &workload.query_workload,
    data_workload: workload.data_workload.as_ref(),
    entry_indices: &entry_indices,
};
let selection = global_selection_with_summary_maintenance_lifecycles(
    &space, demand, now_ms, horizon, capabilities, &cost_model)?;

// 4. Assemble once per root.
for (index, root) in &space.roots {
    assemble_selected_dag_with_summary_maintenance_lifecycles(
        &selection, root, demand, now_ms, horizon, capabilities, &cost_model)?;
}

Steps 1 and 3 carry two bindings — the Id in the roots tuple and the &[usize] in WorkloadDemand — that both have to agree with entries() order, and nothing checks that they do.

After this PR

let output = e2e_plan(
    UserInput::new(&workload, FrontendInput::Sql { catalog: &catalog },
                   PlanningModels::builtin())
        .with_lifecycle(LifecycleInput::new(now_ms, capabilities).with_horizon(horizon))
).await?;

And a different algorithm replaces the stage without touching the pipeline:

impl OptimizationPass for MyPass {
    fn name(&self) -> &'static str { "my-pass" }
    fn optimize(&self, input: OptimizationInput<'_>) -> Result<PlanOutput, OptimizeError> { .. }
}

let output = e2e_plan(user_input.with_pass(&my_pass)).await?;

How

Crate	Added
asap-types	ParsedWorkload — the frontend/optimizer boundary; its constructor checks one lowered expression per normalized entry, so the binding above is an invariant rather than a convention
asap-aware-mapping	OptimizationPass, OptimizationInput, PlanOutput, PlanningModels, LifecycleInput, the optimize harness, PassRegistry, MajorPass
asap-planner (new)	e2e_plan, UserInput, FrontendInput, lowering dispatch

Three points worth a reviewer's attention:

• MajorPass is a move, not a rewrite. The shipped pipeline runs unchanged behind the trait. One consequence: ReplacementStrategy is now a concept of MajorPass rather than of the optimization stage.
• The optimize free function is the harness. A pass is third-party code, but downstream reads every pass's output against one contract, so optimize validates the input and then checks that the variant matches the request, that there is one plan per workload entry, and that plans[k].entry_index == k. Structural only.
• Lowering no longer goes through lower_sql_batch. It walks query_batch alone and silently drops repeating entries — exactly the ones whose RepeatedDemand the lifecycle stage reads.

asap-planner is a separate crate because it is the only one depending on every frontend; a pass depends on asap-aware-mapping and asap-types only, so writing one does not pull in DataFusion.

Tests

12 new tests; cargo test --workspace is 1190 passing, 0 failing.

• 5 unit tests in pass: the contract check rejects a variant the input did not ask for and a plan count that drops a query; the registry refuses a duplicate name and lists names in order.
• 7 end-to-end tests in asap-planner: every query planned in entry order; repeating SQL entries lowered; a caller-supplied pass runs instead of the shipped one; the harness catches a pass that mislabels entry_index; a frontend that cannot lower the workload's language is rejected; disagreeing planning clocks are rejected; lifecycle input selects the lifecycle variant.

Not in this PR

• Candidate-level diagnostics (dag_export's replacements) stay outside the trait — they only exist for a two-phase algorithm. Tools that want them talk to MajorPass and the candidate-search API directly.
• dag_export does not yet take a --pass flag.
• The developer guide's extension-point table (Part 3 §7) does not yet have a row for OptimizationPass.
• Replanning remains undefined.

[Selvomega]

Although I still don't understand why PlanSpace is exposed, this actually looks good to me.

[zzylol]

@Selvomega please feel free to work based on this PR, or please guide whether I should merge this PR. Thanks!