Xsuite 导入与历史实验迁移¶

Xsuite Line 结构导入¶

vm-accelerator-studio-import-xsuite 把 resolved Xsuite Line JSON 投影成 .vmaproj，同时打包：规范 v0.2 结构项目、导入证据、源文件精确字节，以及只读 native Xsuite 绑定。绑定会交叉复核源 entry、字节数、SHA-256、Xtrack 版本、元件清单和项目身份。必须提供独立获得的 expected SHA-256；不匹配时不会产生输出。

./build/dev/vm-accelerator-studio-import-xsuite \
  --input resolved-line.json \
  --output imported-ring.vmaproj \
  --project-id imported-ring \
  --display-name "Imported ring structural projection" \
  --expected-sha256 <reviewed-source-sha256> \
  --project-json imported-ring.studio-project.json \
  --evidence-json imported-ring.import-evidence.json \
  --native-binding-json imported-ring.native-xsuite-binding.json

可投影 Marker、Drift、FirstOrderTaylorMap（仅保长度，矩阵留在源证据）、Quadrupole、Sextupole、Bend（含可选 k1）、LimitRect、LimitEllipse 和 active/inactive Cavity。只有偶极项的 Multipole 会按 Xsuite 约定转换成 corrector：dpx=-knl[0]、dpy=ksl[0]；高阶 Multipole 仍只保位置，精确强度留在源证据。多个 cavity 会各自形成 RF system，并保持 unspecified 角色，避免猜测 main/harmonic 归属。其他可序列化 Xsuite 类型会显示为带标签的保长度 drift 或零长度 marker，完整定义仍由只读源权威保存；非零 relative multipole、退化矩形孔径和超出 portable RF 词汇的 cavity 字段也按此方式保真，不再阻止打包。不一致的椭圆轴和坏矩阵仍会被拒绝。

这是结构浏览和受限编辑，不是 Xsuite 计算等价导入。特别是 FirstOrderTaylorMap 被几何等效为 drift，Bend 的非零 edge angle 和高阶 Multipole 仍只在嵌入源中，因此必须保持 calculationEquivalentToXsuiteSource=false。Studio 会显示 Native Xsuite · read-only source；一旦编辑 portable 投影，状态会明确变为 detached。精确 Engine 加载必须使用三方 hash 绑定的项目、native 描述符和原始源，不能提交降级投影冒充等价格点。

对于仍保持 attached 的 native 包，Screening Study 的 Validate project 会自动使用 Studio–Engine v0.11：协商 ValidateNativeXsuite，经 framed stdin 传输三份精确 entry，并复核规范加载证据、所有身份、顺序 occurrence 数以及源/运行时 Xtrack 版本。存在兼容精确源路线时，Studio 会自动选择；只接受 portable 项目的旧路线会被明确阻断，不会偷偷用非等价投影计算。v0.11 成功只证明精确源可加载，不是物理结果或机器预测。

对于 attached 且未编辑的 native 包，Equilibrium 使用独立的 v0.12 原始 Line 操作。Distribution 使用 v0.13：选择 occurrence 和有界抽样参数后，一次操作会重新核验包绑定、重算 native equilibrium、从同一权威原始 Line 推导局部 optics，并打开已验证的粒子结果；Studio 会留存返回的两个 artifact。这仍是线性、平面、无耦合的 screening；纵向 Gaussian 没有经过 RF separatrix 条件化，也不是机器预测。

Radiation slices 使用 v0.15。它会重新核验三方包绑定，重建权威原始 Line，在有限长辐射元件的中点计算平面 4D optics，只有通过固定 8/32/128 I1–I5 收敛门后才会留存 radiation-slice-model/0.2。这是独立诊断；Studio 不会声称 v0.12 equilibrium 消费了这份切片。薄辐射 kick、skew/强耦合、不支持的场以及机器预测声称都会 fail closed。

Optics 使用 v0.14，在精确原始 Line 上计算常规 4D x/y Twiss。结果为每个权威 occurrence 提供一个入口行，并附带 root-line 出口行；当 c_minus>=1e-6 时会拒绝，结果仍是理想晶格 SCREENING。

Local momentum acceptance 自动使用 v0.16，在精确 Line 上的 12 个确定性观察位置追踪正负稀疏边界。这是坐标空间 screening，不是完整的机器接受度地图。

CPU tracking、Nonlinear Dynamics 和 Errors & Orbit Correction 自动使用 v0.17 精确源路线。由于包内没有权威束团分布，tracking 明确采用固定坐标空间的合成 Gaussian ensemble；结果不是束流预测。非线性结果提供 256/512 圈边界、FFT tune 和 diffusion 证据，不等于机器动态孔径。轨道校正使用确定性的 VIRTUAL BPM/校正器位置，不声称存在已安装硬件或具备 commissioning 性能。用户不需要选择协议或处理 Engine 版本。

Historical Experiment Migration¶

通过 File → Import → Open historical migration catalog… 打开受审阅的 historical-studio-migration-audit/0.2 catalog。工作区支持：

按 tier、Studio status、feature、重复组和全文搜索筛选；
在 unique contents（按 SHA 合并）和 all file instances 之间切换；
将 catalog 中的 logical source 映射到本机目录；
精确复验文件大小和 SHA；
只读查看原 YAML；
将验证证据附加到已保存 .vmaproj；
作为 side-reference 开始手工重建；
把历史 intent/evidence 送入 Screening Study banner。

Historical Migration

一个映射与附加例子¶

假设 catalog 路径以 ssmb-new-steps/... 开头，本机源码根是 /data/ssmb-new-steps：

打开 catalog，点击 Map Sources。
把 logical source ssmb-new-steps 映射到 /data/ssmb-new-steps。
选择记录并点击 Verify Selected。
只有状态为 verified 且 hash/size 精确匹配时，才能附加。
打开或保存当前项目为 .vmaproj，点击 Attach Evidence。
Studio 原子保存、重开并再次验证包；项目 physics revision 不变。

映射只保存在本机设置，不写入 catalog 或项目。绝对/穿越路径、..、符号链接逃逸、缺失或 hash mismatch 都会 fail closed。

三种迁移方式¶

Bounded migration：catalog 已证明能安全映射的有限结构/输入；
Structural project + external experiment：保留结构，外部实验语义仍在历史系统；
Evidence/manual reconstruction：只附加原始证据，由用户在当前项目中显式重建。

Studio 不会从文件名或旧标量推断环周长、harmonic、beam、RF 或 lattice，也不会把历史 GPU 工作改称 CPU、把 DA/FMA 改称普通 tracking，或把历史结果提升为当前 physics revision。

为什么历史页面的 Import Xsuite 可能禁用¶

审计目录可能只提供一个 Xsuite 逻辑路径，却没有独立 expected SHA。由本地文件自己计算出的 hash 不是独立审阅证据，所以按钮保持禁用。获得受审阅 SHA 后，应使用上面的独立命令行结构 importer。