Qlang

Appearance

Phase 7 P7.4 Next Execution Implementation Plan ​

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 在当前 Phase 7 主线上，先把 executable 模式的 async 可用子集补到和既有 library-mode 固定形状 payload 能力更一致，再完成 for await 下一阶段评估，最后收口 Windows 下 clang/archiver 的自动发现与提示体验。

Architecture: 保持 ql-analysis 作为唯一语义真相源，保持 ql-driver::build_file 作为唯一 build orchestration 边界，优先复用 ql-codegen-llvm 已存在的 task-handle/result lowering，而不是为 executable async 单独发明第二套协议。对 Windows toolchain 体验，只在 ql-driver::toolchain 集中补 discover/hint 逻辑，不把平台分支散落到 CLI 和文档层。

Tech Stack: Rust workspace (ql-analysis, ql-driver, ql-codegen-llvm, ql-runtime, ql-cli), VitePress docs, fixture-based CLI blackbox tests, mock toolchain tests

Task 1: 锁定 executable async payload parity 回归面 ​

Files:

  • Create: fixtures/codegen/pass/async_program_main_task_handle_tuple_payload.ql
  • Create: fixtures/codegen/pass/async_program_main_task_handle_array_payload.ql
  • Create: fixtures/codegen/pass/async_program_main_nested_aggregate_task_handle_payload.ql
  • Modify: crates/ql-codegen-llvm/src/lib.rs
  • Modify: crates/ql-driver/src/build.rs
  • Modify: crates/ql-cli/tests/codegen.rs

Step 1: 写失败测试

  • 按照当前已收敛的 async_library_task_handle_payload_families.ql 所覆盖的 tuple / fixed-array / nested aggregate payload 风格，新增三个 async fn main program-mode fixture。
  • 在 ql-codegen-llvm 里给 emits_async_main_entry_lifecycle_with_nested_task_handle_payload_in_program_mode 补齐 tuple / fixed-array / nested aggregate 三类相邻测试。
  • 在 ql-driver 里给 build_file_writes_executable_with_async_main_nested_task_handle_results 补齐对应 executable build 成功回归。
  • 在 ql-cli/tests/codegen.rs 里挂入三个新的 executable 黑盒用例。

Step 2: 运行最小测试集，确认当前缺口

Run: cargo test -p ql-codegen-llvm async_main_entry_lifecycle

Expected: 至少一条新加的 executable aggregate payload 用例失败，或者暴露目前 program-mode 只覆盖单一路径的断言缺口。

Run: cargo test -p ql-driver build_file_writes_executable_with_async_main

Expected: 新增 executable aggregate 用例在实现前失败，或暴露 driver/codegen/runtime contract 不一致。

Run: cargo test -p ql-cli --test codegen async_program_main

Expected: 新增 CLI fixture 在 program-mode parity 未完成前失败。

Step 3: 提交

bash
git add fixtures/codegen/pass/async_program_main_task_handle_tuple_payload.ql fixtures/codegen/pass/async_program_main_task_handle_array_payload.ql fixtures/codegen/pass/async_program_main_nested_aggregate_task_handle_payload.ql crates/ql-codegen-llvm/src/lib.rs crates/ql-driver/src/build.rs crates/ql-cli/tests/codegen.rs
git commit -m "async: lock executable aggregate task-handle paths"

Task 2: 把 executable async lowering 扩到既有固定形状 aggregate 子集 ​

Files:

  • Modify: crates/ql-codegen-llvm/src/lib.rs
  • Modify: crates/ql-driver/src/build.rs
  • Modify: crates/ql-cli/tests/codegen.rs
  • Modify: fixtures/codegen/pass/async_program_main_nested_task_handle.ql

Step 1: 先让 Task 1 的失败测试说明“缺什么”

  • 不要先改文档或新开 ABI surface。
  • 先根据失败点判断缺口是在 render_host_entry_wrapper、render_await、program-mode signature/build path，还是仅仅缺回归覆盖。

Step 2: 最小实现

  • 继续复用 AsyncTaskResultLayout::Loadable 和现有 projection/task-handle lowering。
  • 如果 program-mode 缺的只是 host @main wrapper 的结果装载路径，就只修 render_host_entry_wrapper，不要复制 library-mode await/join 协议。
  • 如果 driver 仍有 program-mode 特判阻塞，就只改 ql-driver/src/build.rs 的最小 gate，不改 ql-analysis truth surface。
  • 不在这一刀里开放新的 async callable/effect surface，不碰 generic async ABI，不碰新的 runtime hook。

Step 3: 运行回归

Run: cargo test -p ql-codegen-llvm async_main_entry_lifecycle

Expected: program-mode 下 tuple / array / nested aggregate payload 回归通过。

Run: cargo test -p ql-driver build_file_writes_executable_with_async_main

Expected: executable async payload matrix通过，已有 for await / nested-task 回归不回退。

Run: cargo test -p ql-cli --test codegen async_program_main

Expected: 三个新 fixture 与现有 async_program_main、async_program_main_for_await_array、async_program_main_nested_task_handle 一起通过。

Step 4: 提交

bash
git add crates/ql-codegen-llvm/src/lib.rs crates/ql-driver/src/build.rs crates/ql-cli/tests/codegen.rs fixtures/codegen/pass/async_program_main_nested_task_handle.ql
git commit -m "async: widen executable aggregate payload support"

Task 3: 文档先行收口 for await iterable 扩展评估 ​

Files:

  • Modify: docs/plans/phase-7-concurrency-and-rust-interop.md
  • Modify: docs/roadmap/development-plan.md

Step 1: 先写评估，不急着实现

  • 在 phase-7-concurrency-and-rust-interop.md 增补一个短矩阵，对比：
    • fixed array（已完成）
    • slice/span view
    • dynamic array
    • 基于 qlrt_async_iter_next 的通用 async iterator hook
  • 明确每条路线对 ABI、MIR、driver capability gate、runtime hook 集合的影响。

Step 2: 收敛结论

  • 明确下一刀优先做“slice/span-like fixed-shape view”还是继续只保留评估态。
  • 明确 dynamic array 和通用 async iterator 继续保持 deferred 的理由。
  • 在 development-plan.md 的 P7.4 小节写成一段可执行的排序结论，而不是泛泛而谈。

Step 3: 验证 docs

Run: cd docs && npm run build

Expected: VitePress 构建通过，新增评估内容不会破坏站点导航。

Step 4: 提交

bash
git add docs/plans/phase-7-concurrency-and-rust-interop.md docs/roadmap/development-plan.md
git commit -m "docs: record for-await iterable evaluation"

Task 4: 收口 Windows clang/archiver 自动发现与提示 ​

Files:

  • Modify: crates/ql-driver/src/toolchain.rs
  • Modify: crates/ql-driver/src/build.rs
  • Modify: crates/ql-cli/src/main.rs
  • Modify: docs/architecture/toolchain.md
  • Modify: README.md

Step 1: 写失败测试

  • 在 ql-driver/src/toolchain.rs 增加 Windows candidate discovery / hint rendering 的单测。
  • 至少锁住一条 “PATH 没有 clang，但存在常见候选路径提示” 的文本回归。
  • 如果 CLI 层有固定输出文本，补一条最小回归，保证错误提示不漂移。

Step 2: 最小实现

  • 在 discover_clang 中继续保留：
    • ToolchainOptions.clang
    • QLANG_CLANG
    • PATH 搜索
  • 然后只在 Windows 分支追加“常见安装位置候选”探测与提示：
    • Scoop/LLVM
    • 常见 LLVM 安装目录
    • 仅提示候选，不在这一刀里做复杂 linker family discovery
  • discover_archiver 延续同样思路，优先补候选路径和更清晰 hint，不做独立大型重构。

Step 3: 运行回归

Run: cargo test -p ql-driver toolchain

Expected: 新增 discovery/hint 单测通过，现有 QLANG_AR_STYLE / wrapper flavor 推断回归不受影响。

Run: cargo test -p ql-driver build_file_preserves_intermediate_ir_on_toolchain_failure

Expected: toolchain 失败仍保留中间产物，新的 hint 不破坏原有失败合同。

Step 4: 同步文档

  • README.md 和 docs/architecture/toolchain.md 要写清楚“自动发现是 best-effort，不是承诺完整系统级安装探测”。
  • 明确继续支持 QLANG_CLANG / QLANG_AR / QLANG_AR_STYLE 作为最高优先级覆盖。

Step 5: 提交

bash
git add crates/ql-driver/src/toolchain.rs crates/ql-driver/src/build.rs crates/ql-cli/src/main.rs docs/architecture/toolchain.md README.md
git commit -m "toolchain: suggest Windows clang candidates"

Task 5: 最终同步 roadmap、索引和全量验证 ​

Files:

  • Modify: docs/roadmap/phase-progress.md
  • Modify: docs/plans/index.md

Step 1: 更新阶段文档

  • Task 2 完成后，把 executable async payload 子集的新事实写回 phase-progress.md。
  • Task 3 完成后，在 docs/plans/index.md 和相关阶段文档中挂出新的执行计划或评估入口。

Step 2: 运行最终验证

Run: cargo test -p ql-codegen-llvm

Expected: backend 回归全绿。

Run: cargo test -p ql-driver

Expected: build/toolchain/runtime gate 回归全绿。

Run: cargo test -p ql-cli --test codegen

Expected: CLI 黑盒 codegen fixture 全绿。

Run: cargo test -p ql-cli --test ffi

Expected: 如本机 clang/toolchain 可用，Rust host 互操作回归继续通过；如环境不满足，保留当前 best-effort 行为并在结果中注明。

Run: cd docs && npm run build

Expected: 文档站构建通过。

Step 3: 提交

bash
git add docs/roadmap/phase-progress.md docs/plans/index.md
git commit -m "docs: sync phase 7 next execution status"

Notes ​

  • 本计划刻意不包含 generic async ABI、cancellation/polling/drop、更广义 async effect surface。
  • ql-analysis::analyze_source、ql-driver::build_file、ql-codegen-llvm 的 async lifecycle lowering、以及 ql-driver::toolchain 仍然是这一轮的四个核心真相面，不要在别的层复制状态。
  • 如果 Task 1 的新回归全部一次通过，不要为了“让计划显得像有实现工作”而硬改代码；直接把 Task 2 缩成文档与测试收口。

Qlang research repository

Copyright 2026