# 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；development source window 若 100%
覆盖需要 262144，但正式 server cap 以 session-sampled paired cell 的实际
`ISL+OSL max` 向上对齐，不能把 full-window 262144 无条件套到低 rho cell。
审计会单独记录并排除 `input_length<=0` 或 `output_length<=0` 的 source
行；这些行只有在 raw trace 同样显示 zero usage/empty response 时才按
“未发生模型执行”处理，不能无记录过滤。

## 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=ACTUAL_CELL_MAX_ROUNDED_UP \
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 中该 paired cell 的实际最大请求；
- `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
```