Skip to content

Document every ASAPPlanner replacement strategy with architecture mapping and an end-to-end example #546

Description

@zzylol

Following the architecture discussion in #509, we need design documentation explaining each replacement strategy in ASAPPlanner, how it works, and where it fits in the planning architecture.

Requested documentation

  • Inventory all existing replacement strategies, with links to their implementations. Distinguish implemented behavior from proposed strategies.
  • For each strategy, explain the input pattern, applicability conditions, assumptions, supported aggregation intents, and the exact transformation or alternatives it produces.
  • Map the strategy to the architecture in docs: propose workload-wide planning, summary sharing, and materialization #509: frontend/logical input, local replacement generation, workload-wide sharing, physical alternatives, materialization, and final selection. Explain which stages the strategy participates in and which decisions belong elsewhere.
  • Explain schema/state contracts, accuracy guarantees and admission checks, required capabilities, cost evidence, and interactions with other strategies. Unknown evidence and unsupported cases must be explicit.
  • Describe how algorithm-developer-provided strategy knowledge is represented and registered in ASAPPlanner, rather than implying that Planner invents replacement algorithms.

End-to-end examples and acceptance

Provide at least one complete example for every strategy, tracing a query workload through initial IR, applicability checks, replacement candidates, sharing where relevant, physical alternatives and materialization choices, selection, execution, and the resulting answer. Include concrete inputs, relevant cost/accuracy assumptions, and expected results. Explain why an alternative is rejected or loses when useful.

Examples must link to executable tests where available and identify missing implementation or test coverage otherwise. Documentation must make it possible to understand a strategy's role without reconstructing its behavior from source code.

Reference: planning architecture proposed in #509.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions