plan-phase4FragmentAssetsAndBuildTimeMerge

Prompt file imported from Han-Zhenzhong/ProtoGPU (.github/prompts/plan-phase4FragmentAssetsAndBuildTimeMerge.prompt.md). Copyright stays with the author.

Plan: Phase 4 Fragment Assets And Build-Time Merge

Replace monolithic mapping-asset editing with fragment-first authoring plus deterministic build-time merge and validation, while keeping runtime interfaces stable and preserving rollback safety.

Steps

1. Phase A: Baseline and guardrails.
2. Capture baseline artifacts using scripts/run_unit_tests.sh, scripts/run_integration_tests.sh, and scripts/compare_dispatch_modes.sh.
3. Record baseline checksums and snapshots for assets/ptx2ir/ptx64_ir_maps.json and assets/ir2uop/ir_uop_maps.json.
4. Phase B: Fragment layout and conventions (depends on 1-3).
5. Introduce authoring directories assets/ptx2ir/fragments and assets/ir2uop/fragments with family/instruction naming conventions.
6. Add authoring docs/examples in assets/ptx2ir/README.md and assets/ir2uop/README.md.
7. Phase C: Merge tool skeleton (depends on 5-6).
8. Implement merge utility under tools/generators/README.md scope with validate/merge/report modes.
9. Add deterministic ordering and canonical serialization in merge output.
10. Add merge-tool tests for command behavior and deterministic re-run equivalence.
11. Phase D: Schema and semantic validation hardening (depends on 8-10).
12. Validate fragments against schemas/ptx_isa.schema.json and schemas/inst_desc.schema.json.
13. Add cross-fragment checks: duplicate signature conflicts, dangling IR ops, unresolved uop ops, and ambiguous mappings.
14. Emit actionable diagnostics with source fragment path and key tuple context.
15. Phase E: Build integration (depends on 12-14).
16. Add CMake merge target and generated outputs in CMakeLists.txt.
17. Generate canonical outputs assets/ptx2ir/ptx64_ir_maps.generated.json and assets/ir2uop/ir_uop_maps.generated.json.
18. Ensure merge failures fail build and test pipelines.
19. Phase F: Runtime/test default cutover (depends on 16-18).
20. Point default runtime/test asset references to generated outputs via src/apps/cli/main.cpp, scripts/run_integration_tests.sh, and tests/tiny_gpt2_minimal_coverage_tests.cpp.
21. Keep compatibility mode for legacy monolith inputs during transition.
22. Phase G: Wrapper and CI alignment (depends on 20-21).
23. Ensure wrappers trigger merge path directly or through CMake dependency.
24. Add merge determinism/validation checks into CI gate.
25. Run full phase gate suites and sign off only when generated-asset path is green.

Relevant files

• docs/doc_design/instruction_extensibility/phase4_fragment_and_merge.md — Phase 4 design reference.
• docs/doc_design/instruction_extensibility/phase4_development.md — Phase 4 development playbook.
• assets/ptx2ir/ptx64_ir_maps.json — current PTX->IR monolith.
• assets/ir2uop/ir_uop_maps.json — current IR->uop monolith.
• schemas/ptx_isa.schema.json — PTX ISA schema.
• schemas/inst_desc.schema.json — instruction descriptor schema.
• CMakeLists.txt — merge target wiring and generated-output dependencies.
• src/apps/cli/main.cpp — default asset path inputs.
• scripts/run_unit_tests.sh — unit wrapper alignment.
• scripts/run_integration_tests.sh — integration wrapper alignment.
• tests/tiny_gpt2_minimal_coverage_tests.cpp — generated-asset regression checks.

Verification

1. Run merge-tool tests for malformed input, conflict detection, and deterministic output snapshots.
2. Run core suites: gpu-sim-inst-desc-tests, gpu-sim-simt-tests, gpu-sim-memory-tests, gpu-sim-observability-contract-tests, gpu-sim-public-api-tests, gpu-sim-tiny-gpt2-mincov-tests.
3. Run wrappers scripts/run_unit_tests.sh and scripts/run_integration_tests.sh.
4. Run mode equivalence via scripts/compare_dispatch_modes.sh with smoke workload/config.
5. Verify generated outputs are byte-identical across repeated merge runs with unchanged fragments.

Decisions

• Included: fragment layout, merge tool, schema+semantic validation, build integration, generated-asset default cutover, CI/wrapper hardening.
• Excluded: runtime dynamic fragment loading, external API changes, one-shot deletion of legacy monolith files.
• Rollout: generated assets become default after gate pass; legacy path remains as compatibility fallback during transition.