[Design] Give lib User One Single lib-func Abstraction

[Selvomega]

This issue is one half of #423, which bundled two separate requirements. It is split into a user-facing issue (this one) and a developer-facing issue on the pluggable optimization pass. #423 is superseded by the two and should be closed.

Problem

Black-box user requirement I embed ASAPPlanner as a library in my own code. I want one entry point that takes all the input I prepared and gives me the optimal DAG. I do not want to know how the planner is staged internally.

Illustration: Where this requirement sits.

Black-box users want one single entry point that covers the whole outer box.

┌─────────────────────── ASAPPlanner -- R1's single entry point ───────────────┐
│                                                                              │
│ raw query  (SQL / PromQL / MetricsQL)       other planner inputs             │
│                   │                         cost model                       │
│                   ▼                         lifecycle info                   │
│   ┌───────────────────────────────┐         accuracy requirement             │
│   │ FRONTEND -- not pluggable     │         ...                              │
│   │ parse ▸ bind ▸ canonicalize   │                   │                      │
│   └───────────────┬───────────────┘                   │                      │
│                   │ pre-ASAP IR                       │                      │
│                   ▼                                   ▼                      │
│       ╔═══════════╧═══════════════════════════════════╧══════════════╗       │
│       ║ OPTIMIZATION PASS -- the slot                                ║       │
│       ║ pick exactly ONE of these                                    ║       │
│       ║                                                              ║       │
│       ║ ┌───────────────┐  ┌───────────────┐  ┌───────────────┐      ║       │
│       ║ │    current    │  │    greedy     │  │    my own     │  ... ║       │
│       ║ │    2-phase    │  │      MQO      │  │   baseline    │      ║       │
│       ║ └───────────────┘  └───────────────┘  └───────────────┘      ║       │
│       ║                                                              ║       │
│       ╚═══════════════════════════════╤══════════════════════════════╝       │
│                                       ▼                                      │
│                          post-ASAP DAG + deployment                          │
└───────────────────────────────────────┬──────────────────────────────────────┘
                                        ▼
                        ASAPQuery-backend / ASAPCollector
                    (downstream -- out of this issue's scope)

Current State and Why It Is Unsatisfying

For black-box users there is no one-call solution. A consumer embedding ASAPPlanner has to assemble the pipeline itself, stage by stage.

What embedding looks like today. Depend on asap-types, asap-aware-mapping, and one frontend crate per query language (asap-frontend-sql, asap-frontend-promql). The only facade re-exporting both frontends is asap-devtools, a developer-tools crate. Then write roughly this:

// 1. lower each query -- per language, with the catalog and accuracy target
let q1 = lower_sql(sql, &catalog, accuracy).await?;   // async (DataFusion)
let q2 = lower_promql(promql, accuracy)?;             // sync

// 2. search
let space = search_workload(vec![("q1", Rc::new(q1)), ("q2", Rc::new(q2))]);

// 3. select
let selection = space.global_selection(&DefaultCostModel);

// 4. materialize -- once per root
let dag = selection.materialize(&space.roots[0].1)?;

// 5. the deployment half -- a separate call with its own arguments
let plan = plan_summary_maintenance_lifecycles(
    dag, demand, now_ms, horizon, capabilities, &cost_model,
)?;

The problem is that the caller does not need to know this much!
Ideally we hope that the user only need to give what he is asked from the above process to one lib function, and get back the optimal DAG and its deployment.

Proposed Mental Roadmap

For the user's requirement: add one library entry point that wraps everything — the prepared inputs in, the optimal DAG and its deployment out.