Prepare Frontier code trace fidelity campaign

runs/frontier-code-trace-v0/README.md

@@ -0,0 +1,118 @@
+# Frontier code-trace campaign handoff
+
+本目录已经准备好无 GPU 的 data preflight、512→16 参数化映射、prefill-only 转换和 `max_model_len` 显式适配。当前没有启动或探测 `dash1`–`dash4`。
+
+完整设计与 gate 见 [`experiment-card.md`](experiment-card.md)。
+
+## 当前已知阻塞
+
+本机 `/home/gahow/ali-trace/trace-glm5.1-formatted/` 不存在。仓库历史记录的远端路径是：
+
+```text
+/home/admin/cpfs/wjh/ali-trace/trace-glm5.1-formatted/
+```
+
+有机器后先确认用户给出的 `~/ali-trace/...` 是否解析到同一目录，再运行以下命令。
+
+## 1. 审计所有 1h+ code source
+
+在持有 trace 的机器、repo 根目录执行：
+
+```bash
+python3 runs/frontier-code-trace-v0/audit_code_trace.py \
+  --trace-root ~/ali-trace/trace-glm5.1-formatted \
+  --output runs/frontier-code-trace-v0/inputs/code-audit.json
+```
+
+如果目录里混有非 request JSONL，先只读列举文件，再用多个 `--source` 显式指定。审计输出必须满足：
+
+```text
+data_gate = PASS
+selected.hash_contract.exact_source_block_size != null
+max_model_len_recommendation != null
+selected.selected_window_stats.max_model_len_coverage[推荐值].coverage = 1.0
+```
+
+旧记录预计 source block size 为 512、推荐 max model len 为 131072，但禁止把这两个值写死为实验事实。
+
+## 2. 物化稳定窗口
+
+```bash
+python3 runs/frontier-code-trace-v0/prepare_code_window.py \
+  --audit runs/frontier-code-trace-v0/inputs/code-audit.json \
+  --output-root runs/frontier-code-trace-v0/inputs/code-window
+```
+
+输出是 60–75min `code-raw-window.jsonl` 和 manifest。source 文件不修改。
+
+## 3. 生成 P+D paired trace
+
+若没有 prompt sidecar，先生成 shape/prefix-faithful synthetic prompts：
+
+```bash
+python3 runs/frontier-s3-real-v0/remap_hash_blocks.py \
+  --input runs/frontier-code-trace-v0/inputs/code-window/code-raw-window.jsonl \
+  --output-root runs/frontier-code-trace-v0/inputs/code-pd-rho-max \
+  --source-block-size 512 \
+  --workload-mode prefill_decode \
+  --rho 1.0 \
+  --max-total-tokens 131072 \
+  --validate-parents
+```
+
+命令中的 `512` 和 `131072` 必须替换为 audit manifest 值。若存在对齐 prompt sidecar，加 `--prompt` 与 `--tokenizer`，并要求 synthetic fallback 为 0。
+
+正式 rho 不能直接用 1.0；先从最大 remap cache 按 session-coherent `sampling_u` 过滤，分别标定 low/mid/near-knee。
+
+## 4. 生成 prefill-only paired trace
+
+对 chat/code 使用同一个转换接口：
+
+```bash
+python3 runs/frontier-s3-real-v0/remap_hash_blocks.py \
+  --input INPUT_WINDOW.jsonl \
+  --output-root OUTPUT_ROOT \
+  --source-block-size SOURCE_BLOCK_SIZE \
+  --workload-mode prefill_only \
+  --rho RHO \
+  --max-total-tokens MAX_MODEL_LEN \
+  --validate-parents
+```
+
+该模式会同时把 Frontier `num_decode_tokens`、real request `min/max_tokens` 和 remapped row 的 `output_length` 固定为 1。
+
+## 5. max-model-len 真机 gate
+
+现有 real runner 新增了三个显式环境变量，chat 默认行为不变：
+
+```bash
+MAX_MODEL_LEN=131072 \
+TRACE_INPUT_ROOT=/absolute/path/to/materialized/code-cell \
+ALLOW_SYNTHETIC_PROMPTS=true \
+OUTPUT_ROOT=/absolute/path/to/new/output \
+bash runs/frontier-s3-real-v0/run_full_real.sh RHO_LABEL tp4_mns16 1 PORT
+```
+
+- `MAX_MODEL_LEN` 必须等于 manifest 推荐值；
+- `TRACE_INPUT_ROOT` 内必须有 `real_requests.jsonl` 和 `manifest.json`；
+- synthetic prompt 默认拒绝，只有在 experiment card 明确降级 claim 后才设为 `true`；
+- runner 会在启动前扫描 paired requests，若任何 `ISL+OSL` 超 cap 立即失败。
+
+正式 full job 前，先按 experiment card 的 G4 补 32k–128k attention profile，再做 TP4→TP2 的 p50/p99/max 单请求与 5min canary。
+
+## 6. decode-only
+
+当前 materializer 故意不提供 `decode_only` 选项。严格 decode-only 需要 initial-KV state，而不是把 prompt 改短。只有 real `DecodeBenchConnector`（或等价能力）与 Frontier initial-KV contract 都通过 G7 后，才创建 decode-only jobs。
+
+## 本地验证
+
+```bash
+python3 -m unittest -v \
+  runs/frontier-code-trace-v0/test_code_trace_preflight.py \
+  runs/frontier-s3-real-v0/test_remap_hash_blocks.py \
+  runs/frontier-s3-real-v0/test_select_chat_window.py
+python3 -m py_compile \
+  runs/frontier-code-trace-v0/*.py \
+  runs/frontier-s3-real-v0/*.py
+bash -n runs/frontier-s3-real-v0/run_full_real.sh
+```