Repository navigation
[Refactor] Clarify configuration-to-physical-plan naming #709
Description
Concrete maintenance problem
The configuration → planning → pricing → installation path uses overlapping terms such as “plan,” “alternative,” “selection,” “leaf,” “mask,” “binding,” “snapshot,” and “config.” Several names describe implementation history rather than the value’s current domain role, making it hard to follow one query from input through an active data-plane plan.
Behavior that must remain unchanged
- Candidate enumeration, feasibility checks, pricing, and cheapest-feasible selection.
- Exact fallback and mixed summary/exact execution behavior.
- Plan publication, staging, activation, and retirement semantics.
- Existing serialized inputs/outputs during a compatibility transition.
Before and after structure
1. Planning input and selected DAGs
BackendLocalPlanningSnapshot→BackendLocalPlanInputBackendLocalImplementation→BackendLocalPlanningInputsPlanningRequest→PhysicalCompilationRequestPlanningQuery→SelectedQueryInputpost_asap→selected_summary_plan_rootlogical_selection→planner_selection_tracewindow_implementations→window_realization_candidateswindow_secs→query_lookback_secondsgroup_by→group_by_labelsaccuracy→accuracy_targetlifecycle→summary_lifecycle_inputserp→empirical_runtime_profile
2. Candidate selection and pricing
materialization_policy→enabled_optional_materializationsmaterialization_candidate_keys()→optional_materialization_ids()- Do not call a
BTreeSet<String>a “mask.” with_exact_alternative()→enumerate_exact_and_materialized_candidates()bind_alternative()→compile_candidate_for_pricing()prepare_manifests()→compile_candidates_for_pricing()AlternativeCost→CandidatePlanEvaluationWorkloadCostComparison→CandidatePlanSelectionReportCostDemand→CostComponentDemandunit→cost_unitmultiplicity→occurrences_per_horizonWorkloadQuote.executable→deployable- Replace free-form candidate
statusstrings with an enum.
3. Physical compilation and publication
PhysicalCompiler→PhysicalPlanCompilerPhysicalPlan→CompiledPhysicalPlancompile_transmission_plan()→build_transmission_plan_from_precompute_plan()publication()→to_publication_artifact()DeploymentEnvironment→PhysicalDeploymentContextsynthesized_window_queries→queries_with_derived_window_candidates- Align
max_retained_summary_byteswithretained_summary_memory_budget_bytes.
4. Data-plane active configuration
build_active_physical_plan()→validate_and_build_active_physical_plan()HotReloadActivePhysicalPlan→ActivePhysicalPlanHandlephysical_plan_snapshot()→active_physical_plan_snapshot()- Rename or split
HotReloadStreamingConfig, since active-plan mode reads configuration fromActivePhysicalPlanwhile legacy mode owns a separately swappable config. ActivePhysicalPlan.runtime_config→streaming_configaggregation_configs→materializations_by_policy_fingerprintget_all_aggregation_configs()→materializations()
Why the proposed structure is minimally complex
This terminology-only refactor preserves the current conceptual boundaries while making the lifecycle explicit:
plan input → candidate requests → compiled candidate plans → pricing evaluations → selected physical plan → active physical plan
No new planner, abstraction layer, or runtime behavior is introduced.
Existing unit and end-to-end protection
Retain and run existing compiler, workload-cost, plan-installation, hot-reload lifecycle, and backend process end-to-end tests. Add focused assertions only where renamed serialized fields require compatibility aliases.
Compatibility or migration impact
For externally serialized or public Rust names, use a staged migration:
- Add new Rust names first.
- Accept old serialized field names via serde aliases.
- Preserve externally used API names temporarily with deprecated forwarding methods where needed.
- Remove aliases only after documented consumer migration.
Acceptance criteria
- Names distinguish planner input, selected DAG, candidate, compiled plan, priced evaluation, selected plan, and active plan.
- No
maskterminology remains for set-valued materialization selection. - Public/serialized compatibility is preserved during the migration.
- Existing planning, pricing, publication, and active-plan lifecycle tests pass.
Blocked by
None - can start immediately
Activity
milindsrivastava1997 commentedon Sep 13, 2026
@zzylol, could you please review this naming-refactor proposal, especially the suggested lifecycle terminology and any externally visible compatibility concerns?
milindsrivastava1997 commentedon Sep 13, 2026
Correction: the issue body compressed several important vocabulary mappings. This is the explicit terminology checklist to preserve during implementation.
leafmaterialization candidateorselected materialization nodematerialization leaf contractseligible materialization candidate keysmask/local maskenabled candidate-key set; do not use “mask” forBTreeSet<String>alternativescandidate requestsbefore compilation;candidate evaluationsafter compilation/pricingbind_alternative()compile_candidate_for_pricing()prepare_manifests()compile_candidates_for_pricing()with_exact_alternative()enumerate_exact_and_materialized_candidates()select()select_lowest_cost_candidate()select_metricsql()select_lowest_cost_metricsql_candidate()select_with_frontend(..., metricsql: bool)select_candidates(..., frontend: QueryFrontend)select_workload_roots()select_summary_plan_roots_for_queries()select_workload_roots_with_trace()select_summary_plan_roots_with_trace()post_asapselected_summary_plan_rootBackendLocalPlanningSnapshotBackendLocalPlanInput(unless immutable capture/provenance is the intended meaning)BackendLocalImplementationBackendLocalPlanningInputsThe key lifecycle vocabulary is:
plan input → candidate request → compiled candidate plan → candidate evaluation / pricing manifest → selected physical plan → active physical plan.milindsrivastava1997 commentedon Sep 13, 2026
Follow-up: these mappings were identified in the complete audit and should be included in this refactor’s scope.
implementationfieldplanning_inputssourceinPlanningQuerylegacy_query_sourceruntime_policymaterialization_runtime_policywindow_candidateswindow_realization_candidates_by_querywindow_implementation_iddefault_window_realization_idquery_staleness_margin_msmax_query_staleness_msevidencetopk_membership_evidence_by_query_idImplementationCostEvidenceWindowRealizationCostQuoteLifecycleCostEvidenceLifecycleCostRatesLifecyclePlanningInputSummaryLifecyclePlanningInputsplanning_request()into_physical_compilation_request()compile()PromQL pathcompile_promql()select_workload_roots_with_erp()select_summary_roots_with_empirical_profile()hybrid_executionallow_mixed_summary_and_exact_executionMaterializationSearchCoverage.scopesearch_scope: CandidateSearchScopecollector_idseligible_collector_idsHotReloadStreamingConfig.from_active()from_active_physical_plan()snapshot()active_snapshot()retire_drained()mark_drained_plan_retired()This completes the terminology mapping from the original audit.
zzylol commentedon Sep 13, 2026
已按审查完成命名迁移，并删除 LegacyMetricWorkload：注册与重规划统一使用 ASAPPlanner 的 QueryWorkload 和 DataWorkload。以下附英文流程图与完整中文报告，包含字段归属、重复判断、源码链接及兼容输入的迁移要求。
实现 PR：#714。英文架构与迁移文档。
English architecture flow
flowchart TB subgraph CP[Control plane] DTO["JSON / YAML compatibility input"] NORMALIZE["Analyzer<br/>Validate and normalize once"] WORKLOAD["ASAPPlanner QueryWorkload<br/>Query + requirements + recurrence + time selection"] DATA["ASAPPlanner DataWorkload<br/>Arrival + rate + cardinality + evidence freshness"] OPTIONS["DeploymentOptions<br/>Sketch constraint + retained labels + wire size + memory cap"] REGISTRY["WorkloadStore<br/>Canonical workload + deployment options per metric and role"] METRIC["Metric deployment planning and replanning<br/>Derive query metadata and fresh cost inputs"] DTO --> NORMALIZE --> WORKLOAD DATA --> WORKLOAD WORKLOAD --> REGISTRY OPTIONS --> REGISTRY REGISTRY --> METRIC INPUT["BackendLocalPlanningInput<br/>Workload demand + physical inputs + deployment context"] LOGICAL["ASAPPlanner + selection adapter<br/>Legal semantic DAG selection"] REQUEST["PhysicalCompilationRequest<br/>QueryCompilationInput + enabled materialization keys"] WINDOWS["Generate window candidates<br/>Cadence + evaluation phase + WindowCostModel"] COMPILE["PhysicalPlanCompiler<br/>Compile concrete candidate plans"] MANIFEST["WorkloadCostManifest<br/>Component implementations and pricing basis"] QUOTE["WorkloadQuote<br/>Provider feasibility and component prices"] EVALUATE["CandidatePlanEvaluation<br/>Select the lowest-cost feasible enumerated candidate"] SQL["ClickHouse SQL selection and binding<br/>Separate compilation path"] PUBLICATION["PhysicalPlanPublication<br/>PhysicalPlanInstallRequest"] WORKLOAD --> INPUT INPUT --> LOGICAL --> REQUEST --> WINDOWS --> COMPILE --> MANIFEST MANIFEST --> QUOTE --> EVALUATE --> PUBLICATION SQL --> PUBLICATION end CONTRACT["Shared asap_types contracts<br/>SummaryCatalog + CollectorPlan + PrecomputePlan<br/>TransmissionPlan + QueryPlan + StorageRouting"] subgraph DP[Data plane] STAGE["Validate and stage RuntimePhysicalPlan"] ACTIVE["Activate via ActivePhysicalPlanHandle<br/>One immutable generation for all readers"] MAINTAIN["Ingest and precompute<br/>StreamingConfigHandle materialization view"] QUERY["Execute installed query DAG<br/>Residual operators, bound reads, exact subqueries"] STORE["Summary storage<br/>SummarySeriesMetadata + physical series state"] STAGE --> ACTIVE ACTIVE --> MAINTAIN --> STORE ACTIVE --> QUERY --> STORE end PUBLICATION --> CONTRACT --> STAGE PUBLICATION -->|OpAMP| COLLECTOR[ASAPCollector] METRIC -->|Stage configuration via OpAMP| COLLECTOR COLLECTOR -->|OTLP frames| MAINTAIN RAW[Raw time-series samples] -->|Remote Write| MAINTAIN QUERY -->|Exact execution or fallback| EXACT[Prometheus / VictoriaMetrics / ClickHouse]完整中文架构审查与命名映射（含最终落地清单）
ASAPQuery-backend 架构与命名审查
审查基线：GitHub
main，b1a58ca810d7b7347f2cc5f30924db56532bbb6b，2026-09-13。关联 Issue：#709。面向维护规划、共享契约、安装及执行代码的开发者。结论：#709 应从“术语替换表”改为“组件边界和数据语义对齐”。优先澄清逻辑候选、物理候选、报价对象、部署状态和存储身份，再决定具体命名。不能因为几个对象都包含计划字段，就把它们合成一个类型；也不能因为都叫
SummaryNode，就认为它们只表示近似查询。本文件保留实施前的架构审查与决策依据。当前实现及迁移规则见 Planning terminology and architecture。其中明确列出此次命名迁移与保留为后续工作的结构调整。
追加实施：删除扁平 workload，统一 canonical 模型
注册模型、输入转换 和 注册存储 已改为直接使用 ASAPPlanner 的
QueryWorkload及内嵌DataWorkload。LegacyMetricWorkload与旧types::QueryWorkload别名删除。RegisteredWorkload只组合 canonical workload 与部署选项，不保存第二份扁平查询字段或ParsedQuery。metric_name、过滤条件、聚合、quantilesQueryWorkload中的完整查询表达式exact_requiredaccuracy/accuracy_slarequirements.accuracyEpsilonDelta完整保留latency_slarequirements.response_latencyrepeat_every/shapetime_windowtime_selection.lookbackseries_count、每系列采样速率DataWorkload.input_cardinality、ingestion_rateDataWorkload.distribution/Evidence<T>DeploymentOptionsdistinct_keys_per_windowWorkloadCharacteristicsQueryId/ deployment model迁移包含有意的入口行为变化：字段式 quantile 生成显式 0.99 分位查询，frequency 生成时间范围内的 item count；不再给已有查询硬塞
quantile。查询与显式 metric/window/aggregation/filter 冲突时返回错误，要求调用者修改查询表达式。旧group_by_labels中用于 collector 保留的标签放在部署选项，不改写查询 GROUP BY。单 metric 注册接口拒绝不能无损投影的多 selector、非等值过滤、offset/@、子查询、
without、历史 time selection、未支持的 cadence 以及未实施的 dollars 约束。更完整的查询继续走已有完整编译接口。数据到达模式与查询周期独立；Batch 表示静态数据，持续 ingestion rate 为零。公开 canonical 构造器也验证这些边界，不能绕过入口校验后静默降级。测试覆盖 canonical 查询与精度/周期/数据证据的存储往返、aggregate sample rate、过期/未知证据、cadence 范围检查及不支持的投影。英文流程架构图见 Planning terminology and architecture。下文中提出临时命名
LegacyMetricWorkload的内容保留为审查历史，已被本节的实际删除方案取代。本 PR 的最终落地与迁移方式
下表记录最终采用的名称；后文保留审查时的备选与理由。实施基线为
cb3153a8（#710），继续复用 Planner 的精度类型；随后合并47d4332f（#711）与ca944a6a（#712、#713、#717），保留主分支的窗口规划、storage routing 和接口清理。BackendLocalPlanningSnapshot→BackendLocalPlanningInput；BackendLocalImplementation→BackendLocalPhysicalInputs；PlanningQuery→QueryCompilationInput；PlanningRequest→PhysicalCompilationRequest；PhysicalCompiler→PhysicalPlanCompiler；PhysicalPlan→CompiledPhysicalPlanpost_asap→selected_plan_root；source→legacy_query_source；window_secs→query_lookback_seconds；group_by→group_by_labels；accuracy→accuracy_target；lifecycle→summary_lifecycle_inputs；runtime_policy→materialization_runtime_policylogical_selection→planner_selection_trace；materialization_policy→enabled_materialization_keys；evidence→topk_membership_evidence_by_query_id；hybrid_execution→allow_mixed_summary_and_exact_execution；synthesized_window_queries删除：编译器来源标记改为每个候选的derived/cohort_only，不接受序列化输入WindowImplementationCandidate→WindowRealizationCandidate；ImplementationCostEvidence→WindowRealizationCostQuote；LifecycleCostEvidence→LifecycleUnitCosts；LifecyclePlanningInput→SummaryLifecyclePlanningInputs；window_implementations→window_realization_candidatessnapshot_version→schema_version；implementation→physical_inputs；外部窗口候选与默认窗口字段随 #712 删除，改用window_cost_model；编译器在逻辑选择后按 cadence / phase 生成候选；max_retained_summary_bytes→retained_summary_memory_budget_bytesDeploymentEnvironment→PhysicalDeploymentContext；collector_ids→target_collector_ids；query_staleness_margin_ms→query_retention_margin_msCostDemand→CostComponentDemand；unit→pricing_basis；multiplicity→occurrences_per_horizon；AlternativeCost→CandidatePlanEvaluation；WorkloadCostComparison→CandidatePlanSelectionReport；alternative_id→candidate_id；physical_alternative_id→physical_candidate_id；alternatives→candidate_evaluationswith_exact_alternative→enumerate_exact_and_materialized_candidates；bind_alternative→compile_candidate_for_pricing；prepare_manifests→compile_candidates_for_pricing；select→select_lowest_cost_candidate；select_metricsql→select_lowest_cost_metricsql_candidatestatus使用CandidateEvaluationStatus；覆盖范围使用CandidateSearchScope；兼容未知字符串与原缺省值。原PhysicalQueryFrontend移到共享编译入口并命名为QueryFrontend，替代内部布尔参数query_plan::logical::LogicalOperator→query_plan::residual::ResidualQueryOperator；backend 对应模块迁移到residual，保留旧模块导出ActivePhysicalPlan→RuntimePhysicalPlan；HotReloadActivePhysicalPlan→ActivePhysicalPlanHandle；HotReloadStreamingConfig→StreamingConfigHandle；runtime_config→streaming_config；active handle 的snapshot→active_snapshot；from_active→from_active_physical_plan；retire_drained→mark_drained_plan_retiredSketchInstanceMetadata→SummarySeriesMetadata；sketch_index字段与变量 →summary_store；保留SketchStore类型types::QueryWorkload/LegacyMetricWorkload删除，统一到 PlannerQueryWorkload+DataWorkload；ClickHouseSqlWorkload.sds→summary_catalog；aggregation_configs→materializations_by_policy_fingerprint；aggregation_id_for_key/value→key_policy_fingerprint/value_policy_fingerprint；data_plane::monitor→update_sampling主分支集成补充：共享 pane 保留 cadence、phase 与 evaluation alignment；发布的 storage routing 从选中物理计划生成；
types_v2已删除，定义合入types。随后合入 #715（e25d53b1），保留未使用的 auto/Pareto 规划、rollback/diff HTTP 接口及辅助模块删除；canonical 注册与重规划仍走保留入口。这些上游删除的接口不提供旧字段兼容。下文涉及旧窗口模板和 query 级来源集合的建议仅属历史审查。迁移规则：保留字段的 Rust 名称更新，输出 wire 名称保持原样；反序列化接受新名称作为 alias。旧公共类型导入及主要入口提供 deprecated 转发，但 Rust struct literal 的旧字段拼写无法通过类型别名兼容，源码消费者需要按表迁移。
None/ 空候选集合、浮点频次、报价身份、候选排序、严格小于的选择规则及计划生命周期均保持原义。erp保留并明确为 Error–Resource Profile；WorkloadQuote.executable保留，因为它不代表安装或部署已经通过验证。双模式 streaming handle 的读写行为只补充说明；拆分写 API、删除 legacy 路径、统一 SQL 定价以及 typed ID / 时间单位迁移留作独立工作。英文流程图与边界说明见 Planning terminology and architecture。一、组件职责与当前真实路径
control_plane::planner_selectionselection必须说明是 logical 还是 physical；trace 不是决定执行行为的配置physical::compilerPhysicalPlanCompiler比PhysicalCompiler清楚；整个模块当前职责仍比单纯 lowering 更宽physical::workload_costphysical::erpempirical_runtime_profile是错误展开；输入还包含策略与观测，不只一个 profilecontrol_plane::clickhouseClickHouseSqlWorkload.sds实际是SummaryCatalog；SQL 当前没有走同一套workload_cost::select整计划报价流程asap_typescontrol_plane中若仅 re-export，不是重复类型physical::publication+ backend client + OpAMPPhysicalPlanLifecycleActivePhysicalPlan被用于 staged map，名称把类型和生命周期阶段混在一起SeriesIdResolvercollector_id是特定生产者身份；不能把所有 producer 无条件改叫 collectorPrecomputeEngine+ workers + maintenance runtimePrecomputeEngineConfig是 worker/队列等引擎设置，StreamingConfig是 materialization 的运行时视图，不是重复配置SketchStore+ backfill / persistenceSketchStore已比名称更广；领域表述宜用 summary store。全仓类型迁移可独立进行control_plane::monitor/replandata_plane::monitormonitor太宽，与 CP 的指标/SLA monitor 不同；建议模块领域名update_samplingasap_otel_prototools/scripts/ demos英文流程架构图见 Planning terminology and architecture。下文表格的“当前名称”指审查基线上的名称，右栏是迁移建议。
二、不要把系统画成一条所有入口都相同的流水线
PromQL / MetricsQL 的主要计划路径是：
工作负载与证据 → Planner 语义选择 → 工作负载级物理候选 → 编译结果与 manifest → provider quote → 最低成本可行候选 → publication → runtime generation这里有三个不同范围的选择：语义 DAG 的选择、单个窗口物理实现的选择、整个工作负载物理候选的成本比较。它们并非重复实现。
with_exact_alternative的有界枚举也不保证找到所有未枚举实现的全局最优值。相同成本时，当前严格<比较保留先出现的候选。编译器、候选与定价prepare_manifests()编译后丢弃 plan，仅返回 manifests 和诊断行；部署选择阶段重新编译候选，再与证据中的 manifest 做完整相等比较。这是“发现/采集成本”和“使用成本部署”两个阶段，不应因为函数都做 compile 就直接删除其中一个。C2ClickHouse 的自动路径直接从 SQL 选择与绑定构建
PhysicalPlanPublication；已有 catalog 路径接收sds + precompute_plan + transmission_plan。它们与 PromQL 共用安装及运行时契约，但不能画成已经共用相同的整计划报价选择过程。建议两个请求对象分别叫ClickHouseCompilationInput、ClickHouseBindingInput，或保留现名并明确 automatic / catalog-bound 区别。C3旧 flat workload →
CollectionPlan/ stage emission 路径仍有实际调用；PhysicalPlanner、PlanNode、PostAsapPlan等旧模块也留在公开模块树中。不要据名字推断它们都与当前PhysicalPlan等价，也不要据旧模块存在就断定它们全部处于主路径。C4三、#709 中应该修正或收紧的映射
erp→empirical_runtime_profileErpPlanningInput还含观测、匹配策略、mode、权重和能力erp并写明定义，或字段error_resource_planning_input；不要使用错误全称PlanningQuery→SelectedQueryInputselect_workload_roots_with_trace(&mut queries, ...)更新；并非整个生命周期都已 selectedQueryCompilationInput，不用类型名承诺当前代码没有保证的阶段post_asap→selected_summary_plan_rootKeepPreAsapexact 根selected_plan_root/selected_logical_root；不要暗示必定 materialized 或 approximatematerialization_candidate_keys()→optional_materialization_ids()SummaryDefinitionId不是一类身份eligible_materialization_keys()；保留 key 与已绑定 ID 的区别materialization_policy→enabled_optional_materializationsOption<BTreeSet<String>>：None启用全部 eligible，Some(empty)不启用任何可选项enabled_materialization_keys，保留并明确三态语义；不要默认成普通空集合materialization_leaf_contract→ 候选 keysraw_materialization_input_contract；真正枚举 keys 的函数另行命名leaf改为 materializationCostDemand.unit→cost_unithorizon/query_evaluation，表达报价的工作量基准，并非 CPU 秒、字节或货币单位pricing_basis/demand_basis；可定义PricingBasis枚举multiplicity→occurrences_per_horizonLifecycleCostEvidence→LifecycleCostRatesLifecycleCostModel/LifecycleUnitCosts，不应全称 ratesWorkloadQuote.executable→deployableexecutable或用provider_feasible；不要暗示已通过端到端部署检查synthesized_window_queries→queries_with_derived_window_candidatescompiler_priced_window_query_ids；derived 已用于“由 summary 派生 summary”，易混淆collector_ids→eligible_collector_idsCollectorPlantarget_collector_ids；代码没有在这些 eligible collector 中再选子集query_staleness_margin_ms→max_query_staleness_msquery_retention_margin_ms，或保留现名并说明用途；避免暗示已有 admission enforcementBackendLocalImplementation→BackendLocalPlanningInputsBackendLocalPlanningInput，内层倾向BackendLocalPhysicalInputs；不为这些分类额外创建一组 wrapperActivePhysicalPlan保持不动，只改 handleRuntimePhysicalPlan；handle 用ActivePhysicalPlanHandle，phase 由 lifecycle 管理build_active_physical_plan→validate_and_build_active_physical_planvalidate_and_build_runtime_plan；否则名字仍把构建和激活混淆snapshot()→active_snapshot()runtime_policy→materialization_runtime_policyRuntimeRulePolicy具体控制 sampling、delta、GOS 与 adaptation依据：编译输入与选择 C1、候选与定价 C2、ERP C5、候选 key C6、pane 重定价 C7、运行时生命周期 C8。
以下映射方向正确，可以作为同一轮小范围迁移：
PlanningRequestPhysicalCompilationRequest；包含 workload 上下文，不是单 queryPhysicalCompilerPhysicalPlanCompilerPhysicalPlanCompiledPhysicalPlan；候选和获选结果可继续复用此类型，无须新增SelectedPhysicalPlanwrapperlogical_selectionplanner_selection_trace；说明只做诊断window_implementationswindow_realization_candidates；对象WindowImplementationCandidate也应相应命名ImplementationCostEvidenceWindowRealizationCostQuote；保留 model、时效与 workload scopewindow_candidateswindow_realization_candidates_by_query；注明 key 为注册查询文本，不是 query IDwindow_implementation_iddefault_window_realization_id，已选估计项用window_realization_id，不能全仓统一加 defaultPlanningQuery.window_secsquery_lookback_seconds；不可连带重命名其他类型的所有 window 字段PlanningQuery.sourcelegacy_query_source可接受，但该值也写入 workload cost manifest，不能借改名删除或改变其报价身份group_by/accuracygroup_by_labels/accuracy_target；输出精度结果不能改叫 targetlifecycle/LifecyclePlanningInputsummary_lifecycle_inputs/SummaryLifecyclePlanningInputsPlanningRequest.evidencetopk_membership_evidence_by_query_id；输入 map 的topk_evidence是按查询文本，不应加 by_query_idhybrid_executionallow_mixed_summary_and_exact_execution；是允许编译的模式，不是本次请求必然采用混合执行bind_alternative/prepare_manifestscompile_candidate_for_pricing/compile_candidates_for_pricing；后者返回清单及诊断，不返回编译 planswith_exact_alternativeenumerate_exact_and_materialized_candidates；保留有界搜索与枚举顺序AlternativeCostCandidatePlanEvaluation可接受，但必须允许尚未定价或编译失败；更中性的CandidatePlanDiagnostic也符合现有全阶段用途WorkloadCostComparisonCandidatePlanSelectionReportselect/select_metricsqlselect_lowest_cost_candidate/select_lowest_cost_metricsql_candidate；文档写明 feasible 与枚举范围metricsql: boolQueryFrontend；先审计已有PhysicalQueryFrontend，不要再建第三份枚举；SQL 并未因此自动适配此入口CostDemandCostComponentDemandpublication()to_publication_artifact()，或沿用publication()；它构造并校验制品，不执行 HTTP 发布compile_transmission_planbuild_transmission_plan；从 precompute 和 runtime policies 构造，不一定要把全部参数编码进长函数名DeploymentEnvironmentPhysicalDeploymentContext；target、capability、time、generation 都是上下文max_retained_summary_bytesretained_summary_memory_budget_bytes，保留旧缺省值、别名与具体计量定义ActivePhysicalPlan.runtime_configstreaming_config，准确表达持有的配置类型aggregation_configsmaterializations_by_policy_fingerprint；目前 key 是u64形式 fingerprint，改名不等于已经升级 typed keyget_all_aggregation_configs()materializations()；明确当前仍返回 mapfrom_active()from_active_physical_plan()retire_drained()mark_drained_plan_retired()；它标记 lifecycle status，不执行存储 GC四、全仓中 #709 漏掉的歧义与重复
types::QueryWorkload与 Plannerworkload::QueryWorkloadLegacyMetricWorkload或导入时显式 aliasPlanNode/CollectionPlan/PhysicalPlan/QueryPlanQueryPlan与QueryPlanEntryQueryExecutionCatalog/QueryExecutionPlan，#709 不必强行扩展query_plan::logical::LogicalOperatorResidualQueryOperator，模块residual；对应prepare_logical按实际职责命名ClickHouseSqlWorkload.sdsSummaryCatalog，不是单个 Self-Describing Summarysummary_catalogAggregationConfig与PrecomputeMaterializationPrecomputeMaterialization；保留旧 alias 过渡，不复制定义AggregationIdInfo.aggregation_id_for_key/valuekey_policy_fingerprint/value_policy_fingerprint；typed ID 迁移单独评估SummaryDefinitionId与PolicyFingerprintSketchInstanceMetadataSummarySeriesMetadata，避免与SummaryInstance混为一个窗口对象SketchStore/sketch_indexsketch_index变量可先改summary_store，全面类型迁移另行处理SummaryCatalog/sketch_catalog/ SQL catalog /PolicyRegistrysummary catalog、sketch capabilities、source schema catalog、materialization lookupPrecomputePlan.materializations与StreamingConfig.aggregation_configsPhysicalPlan/ Publication / InstallRequest / Runtime planHotReloadStreamingConfig.inner与.activeswap仍写 inner，写入不成为 snapshot 的结果summary_exec/summary_executorsummary_execution/store_summary_reader，保持执行语义边界control_plane::monitor与data_plane::monitorsummary_catalog/sds/canonical中的 re-export依据：旧 workload C4、共享 materialization C9、SDS C10、catalog C11、runtime config C12、存储元数据 C13、residual operators C14、shared publication C15。
五、必须保留的身份、时间和生命周期区别
plan_id / plan_version标识部署决定与世代；CatalogGeneration额外携带 catalog 的摘要。SummaryDescriptorId表达算法/状态语义，DataDescriptorId表达输入 population；SummaryDefinitionId绑定这些定义与物理布局。SID 表达具体物理 series 生命周期，而SummaryInstance表达具体时间范围和 group 的状态，并携带物理引用、来源与完整性。不能因为底层有些都用 u64，就全部命名为id或materialization_id。SDS、Catalog、存储元数据window至少有 query lookback、evaluation interval、stored pane duration、slide、origin、retention、producer emission cadence 等含义。PrecomputeMaterialization::stored_window_ms()对 FullWindow 与 pane layout 的处理不同，不能全仓把window_size替换成query_lookback_seconds。改名应保留各字段当前单位；单位转换属于额外行为变更。C9生命周期至少有三条轴：计划
Staged / Active / Draining / Retired，materializationMaterializing / Ready / Serving，以及具体实例的 completeness。一个计划已 Active，并不表示其每个查询范围都已完整；读路径仍需校验状态。retire_drained只是状态标记，不表示已经回收所有持久化数据。计划生命周期、SDSsnapshot对 immutable catalog 和Arc读取是合适术语，不应一律删除。对于BackendLocalPlanningSnapshot，代码主要将其消费为输入，改成 input 合理；但要同时决定snapshot_version的 schema 名称和兼容策略。六、迁移与验收建议
physical的旧路径隔离、hot-reload handle 拆分和 shared schema 版本升级分别处理。serde(rename = "old_name")固定旧名称，视需要接受新名 alias。仅alias = "old_name"无法保护旧消费者读取新输出。还需检查手工 JSON/YAML 生成、Python 校准与回放工具、CLI 输出和已有 fixture。status与search_scope时保留原 wire 表达，或明确版本迁移。现有 status 含bind_failed、bound、evidence_missing、rejected、evidence_invalid、unselected、selected，且status缺省为空字符串。typed scope 还应保留“bounded inventory 不承诺未枚举最优”的解释信息。额外维护问题：
docs/developer_docs/data-structure-ownership-audit.md仍说多个 wire DTO 在 control_plane、尚待搬迁，但当前已经在asap_types；PrecomputeEngine注释还称 Remote Write 已删除，而 driver 与启动代码中已存在。命名 PR 应同步修正相关陈旧说明，否则新的词汇表仍会被旧架构描述覆盖。