Skip to content

docs: define ASAPPlanner input, output, and workflow - #445

Open
zzylol wants to merge 22 commits into
mainfrom
docs/issue-438-planner-contract
Open

zzylol wants to merge 22 commits into
mainfrom
docs/issue-438-planner-contract

Conversation

@zzylol

@zzylol zzylol commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Why

Issue #438 shows that the current documentation exposes individual planner stages without first defining the supported end-to-end integration workflow. Callers cannot easily tell which inputs are required, when lifecycle planning is necessary, or whether PlanSpace, a ranked group, or a materialized DAG is the final output. Related terminology and API-surface ambiguity is tracked in #427, and #428.

Before this PR

A caller could discover search_workload*, cost_sorted, global_selection, and lifecycle APIs independently and reasonably conclude that each was a separate valid end state. For example, a recurring summary could be structurally selected without making clear that this does not establish that maintaining it is cheaper than exact recomputation. Window semantics, summary frameworks, physical layouts, window edges, and physical handoffs were also easy to conflate.

After this PR

The design documentation starts from one outer workflow: canonical roots and requirements enter ASAPPlanner, and PlanSpace is the canonical logical output. It then explicitly documents:

  • required, optional, and optimization-specific inputs;
  • the meaning and categories of evidence;
  • PlanSpace, ranked views, materialized DAGs, and lifecycle-aware outputs;
  • inspection, structural-selection, and lifecycle-aware workflows and their promises;
  • replanning as a fresh invocation with a new workload/evidence snapshot; and
  • ownership-specific vocabulary for query windows, summary frameworks, physical layouts, pane layouts, window edges, physical handoffs, and comparison scopes.

The lifecycle-aware workflow is identified as the recommended path before claiming that maintained summary state is preferable to raw execution. Physical binding, deployment, transitions, and execution remain downstream responsibilities. The document also states that public Rust visibility does not automatically make a type part of the recommended integration surface.

Validation

  • git diff --check
  • verified all relative links added by the document resolve locally

Closes #438
Related to #427 and #428
Related to ProjectASAP/ASAPQuery-backend#734

@zzylol zzylol changed the title docs: define ASAPPlanner input, output, and workflows docs: define ASAPPlanner input, output, and workflow Sep 18, 2026
@zzylol
zzylol removed the request for review from milindsrivastava1997 September 18, 2026 18:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Input/Output and Proper Workflow of ASAPPlanner

1 participant