light-experiment-coding

实验编码（stage 6）

任务不是“写出能跑的 notebook”，而是把上游冻结计划逐行实现成可证伪、可复跑、可审计的实验。优先级：

1. 不改研究问题；
2. 不让评估信息进入训练；
3. 能用固定环境与 seed 真复跑；
4. 保留足够 raw evidence，让 result-analysis 自己重算；
5. 代码整洁和速度服从以上约束。

先完整阅读 references/experiment-coding-resource-map.md。工具机制见 references/tools.md，TDD/调试红旗见 references/tdd_redflags.md 与 references/debug_protocol.md。

入口：冻结输入

开始写码前读取并 hash：

• question / estimand；
• experiment matrix 每一行和 fair-comparison 常量；
• pre-registration 及 provenance；
• failure-tree report：每条 hypothesis 的 success/failure/inconclusive 分支、guardrail/counter-metric、kill criterion 与 amendment policy；
• data fixed revision、raw/curated SHA256、lineage、split ID、split_leakage evidence；
• result-analysis 对 raw run、predictions、metrics、failures、provenance 的消费契约；
• 当前 git commit 与 dirty state。

primary outcome、comparison family、exclusion、stopping 已冻结。若实现证明计划不可行，带最小复现和影响返回 research-plan，停下让人决策；不得改 config 默认值静默漂移。

实现顺序

1. 建立最小可运行项目

优先复制 assets/project-scaffold/：

• uv.lock + pyproject.toml：uv sync --locked --extra dev；
• configs/experiment.schema.json：每个 matrix row 的机读配置；
• experiment_contracts.py：data/model/metric/preprocessing 最小接口；
• reproducibility.py：运行期 seed helper；
• CI/pre-commit/debug 资产。

遵循现有仓库框架和配置格式；不要为一个实验引入付费 IDE、云追踪或私有 key。MLflow/DVC 可选，普通本地文件必须能完成 核心闭环。不可用资源明确写 UNAVAILABLE:原因，不假装通过。

2. 测试先行

在实现 preprocessing/train/eval 前：

1. 写 gold test，验证人工可算的小答案；
2. 写 property test（Hypothesis），验证范围、有限性、对称/单调等不变量；
3. 写 metamorphic test，验证置换/等价变换后的输出关系；
4. 写 train-only-fit 测试，记录 transformer 只收到训练折；
5. 亲眼看新测试因缺实现或真实 bug 失败，再写最小实现使其通过。

浮点断言用 pytest.approx / assert_allclose(rtol, atol)。先声明 device、dtype、mixed precision 和容差；NaN/Inf 默认 fail。不要测“随机训练一定达到某个漂亮数”，测确定性边界和可重算事实。

3. 防泄漏实现

• holdout：先 split，再仅用 train fit/fit_transform，test 只 transform；
• CV/调参：预处理器与模型放进 sklearn Pipeline，每折只 fit training fold；
• 患者/用户/牧场等实体用 group-aware split，不得跨 train/test；
• 目标编码、特征选择、PCA、imputation 同样只在训练折 fit；
• 数据件复核直接复用 data-engineering split_leakage，不重造。

review_gate 只识别静态形态，会漏/误报；领域语义仍要人工核对。指标异常好，先查 leakage。

4. 控制随机性与数值边界

分开两个目的：

• fixed_repro：固定一个 seed，在同代码/data/config/environment 下做两次独立运行；
• randomness_estimation：按预注册 seed 列表做多次运行，估计算法随机性。

多 seeds 不是患者/实体样本量，绝不拿 seed 数替代功效分析 n。

按实际使用覆盖 PYTHONHASHSEED（当前进程须启动前设）、random、NumPy、框架 RNG、CUDA、cuDNN、 deterministic algorithms、DataLoader generator/worker。记录 device/dtype/AMP、线程数、worker 数、排序键和已知 非确定算子。换 seed 应可变但可追溯；同 seed 一致也只支持同环境契约，不外推跨 release/platform/hardware bitwise 保证。

5. 每个 run 保留 raw bundle

从 templates/run_manifest.template.json 生成 light.run_manifest.v3；说明见 templates/run_manifest.md。 termination 只说明进程为何停止，completion 才记录矩阵行 oracle 是否真的通过； timeout / max iterations / cancel 一律不得冒充完成。

每个 matrix row × config × seed × attempt 独立目录，至少保存：

• config schema 校验后的快照；
• code commit/dirty/diff 与代码文件 hash；
• data/input SHA256、source revision、split ID；
• environment（Python/包/OS/CPU/GPU/CUDA/线程）；
• argv 数组、stdout、stderr、exit code；
• 每折/每实体 raw metrics、patient/entity-level predictions；
• test evidence；
• failed run 的 failure artifact。

失败 run 不删除，不覆盖成成功。禁止只交 summary CSV；result-analysis 必须能从 raw evidence 重算。

ゲートとチェックポイント

以下の順序で実際に実行し、終了コードを記録します：

python scripts/experiment_execution_contract.py --spec experiment_execution_contract.json \
  --report execution_contract_findings.json --json-out execution_contract_report.json
python scripts/review_gate.py src/ --json
python scripts/seed_audit.py src/train.py src/reproducibility.py
python scripts/repro_gate.py --spec repro_spec.json --report repro_findings.json
python scripts/run_artifact_check.py --manifest runs/EXP-01/run-a/manifest.json
python scripts/run_artifact_check.py --compare \
  runs/EXP-01/run-a/manifest.json runs/EXP-01/run-b/manifest.json
python ../light-orchestrator/scripts/run_checkpoint.py \
  --file .light/passport.yaml --stage 6 --findings repro_findings.json --write --ts <ISO-8601>

experiment_execution_contract.py は light.experiment_execution_contract.v1 を消費します（テンプレートは templates/experiment-execution-contract.example.json を参照。意図的に fail-closed です）。as_of、凍結済みのスコープ／評価器／予算、失敗ツリーの引き継ぎ、マトリックス／DAG、実行ステータス／終了／失敗クラス、部分チェックポイント／再開コマンド、環境とキャッシュの来歴、再現性レベルの区分、リモート／有料実行の承認を検証します。timeout/OOM/preempted/max-iterations を completed と記録してはいけません。frozen_at とリモート承認の approved_at に未来の日時を設定してはいけません。decision=NOT_READY/UNKNOWN 自体が進行を阻止します。実行は凍結済みの matrix_rows 内の row に紐付いていなければならず、各 row は failure_tree_refs（hypothesis_ids、branch_action_ids、該当する guardrail_ids）に紐付いていなければなりません。実験行を追加する場合は、先に research-plan を改訂します。上流で guardrail が要求されている completed run では、completion に guardrail_evidence_artifacts を残す必要があります。そうでなければ result-analysis に渡してはいけません。実際の walltime/cost/compute_units とリモートの推定コストが、凍結済みの予算を黙って超えてはいけません。超過する場合は予算超過の承認が必要です。PARTIAL/RESUMABLE には checkpoint SHA と resume command が必要です。CLEAN_ENV_RERUN/CROSS_PLATFORM/INDEPENDENT_REIMPLEMENTATION を要求する場合は、対応する証拠が必要です。リモート／有料／HPC 実行は、user_authorization=APPROVED になるまで RUN_READY にしてはいけません。

stage 6 の canonical critical は次のものだけです：

• leakage；
• reproducible。

研究チェックポイントでは、spec に従い float/security は warn です。review_gate は独立した成果物の阻止ゲートとして設定できますが、これを利用してチェックポイントの critical 範囲を拡大してはいけません。 stage-6 ゲートの失敗はこの段階で修正し、ROUTES[6] の出辺を捏造してはいけません。

同じ固定 seed での 2 回の実行は、それぞれ別の run dir にする必要があります。run_artifact_check.py でまずマトリックス／config／env／code／input の同一性と started_at/ended_at のタイムライン（タイムゾーン付き、順序が逆転しておらず、未来の日時ではないこと）を確認してから、predictions/raw_metrics の hashes を比較します。 静的な seed/leakage ゲートと同じ seed のペアの両方を通過しても、それは境界のある証拠の一組に過ぎません。

result-analysis と 7→6 の受け渡し

completed/failed の全 run、coverage、manifests、predictions、raw metrics、logs、test evidence、canonical findings をすべて引き渡します。 stage 6 で result-analysis のために run を選別して除外したり、先に結論を書いたりしてはいけません。

result-analysis が実装上の実際のバグ、または再現不能な root causeを特定した場合に限り、orchestrator は次を実行できます：

python ../light-orchestrator/scripts/reroute.py \
  --findings result_findings.json --stage 7 --passport .light/passport.yaml

reroute は提案のみです。7→6 back-edge を追加する前に停止し、ユーザーの判断を仰いでください。ユーザーの確認後に限り、passport の add-back-edge を呼び出し、根本原因を解決するための失敗したコマンド、 期待値と実際の結果、artifact pointers を添えます。統計的に有意でないこと、効果が小さいこと、計画が実行不可能であることは、自動的に実装上のバグを意味するものではありません。

譲れない条件

1. 全データで scaler/encoder/imputer/PCA/feature selector を fit してから split/CV しない。
2. フレームワークの seed を 1 つ設定しただけで、再現可能だと主張しない。
3. 浮動小数点値の == によるアサーションを使わず、NaN/Inf を黙って無視しない。
4. 固定 seed と複数 seed の科学的な目的を混同しない。
5. 失敗した run を削除せず、集計値だけを残さず、stdout/stderr/predictions/raw metrics/provenance を必ず含める。
6. 静的スキャンを「漏洩がないことの証明」と記載せず、同じ seed での 2 回の一致を「ハードウェアをまたいだ完全な再現性」と記載しない。
7. 凍結済みの研究設計を変更しない。実行不可能な場合は research-plan に戻して人が判断する。
8. stage 6 が独自に出辺を作らない。7→6 は下流で実際の root cause が提案された場合に限り、ユーザーの承認後にのみ追加する。

完了条件

• 各 matrix row に schema-valid な config と安定した run ID がある；
• experiment_execution_contract.py を実行したか？scope/evaluator/budget、DAG、run status、failure class、resume、resource costs、repro level、リモート承認はすべて整っているか？
• execution contract は .light/failure_tree_report.json の locator/hash/status に紐付いているか？各 matrix row に failure_tree_refs があるか？completed run に guardrail evidence が残されているか？
• as_of、frozen_at、リモートの approved_at、run の started_at/ended_at はすべて実際に発生した日時か？未来の日時を事前入力しておらず、終了が開始より前になっていないか？
• run の matrix_row_id は凍結済みの experiment matrix に由来しているか？実際の walltime/cost/compute_units またはリモートの推定コストが予算を超過する場合、予算超過の承認があるか？
• gold/property/metamorphic/train-only-fit テストで、まず失敗し、その後成功している；
• lock、インターフェース、device/dtype/AMP/NaN/Inf/許容誤差の境界が明確である；
• review/seed/repro ゲートと stage-6 checkpoint を通過している；
• 同じ固定 seed での 2 回の predictions/raw_metrics hashes が一致している；
• seed を変えた場合の変化を manifest で追跡できる；
• 各 run の config/env/code/input/log/raw metric/prediction/failure evidence が揃い、hash で検証できる；
• result-analysis が bundle だけで処理でき、plan drift や未承認の back-edge が発生していない。

名称と実態の整合

TDD、seed、セキュリティスキャン、再現実験はいずれも Light 独自のものではありません。R1 の真に同種のツールは、すでに config-first、smoke、immutable run、 lineage、keep/discard を広く備えています。ここで実際に追加されるのは次の点です：

1. コードレベルでの holdout/CV leakage；
2. フレームワークを考慮した seed audit；
3. 再利用可能なデータコンポーネントの split_leakage；
4. frozen execution contract（scope/evaluator/budget/DAG/status/resume/repro level/remote authorization）； Round 3 では、run と凍結済み matrix row の同一性の紐付け、および実際／推定のリソースコストに対する予算超過ゲートを追加し、新しい実験行や有料の実行拡大が上流の承認を迂回するのを防止； Round 3 ではさらに、failure-tree handoff と guardrail evidence を追加し、research-plan の失敗／結論なし／kill criterion が実行段階で失われないようにする；
5. hash-verified raw run bundle ＋同じ seed のペア；
6. canonical findings/stage-6 checkpoint ＋ユーザーが制御する 7→6。

正直に述べると、MLflow のようなクエリ UI、DVC remote、GPU scheduler、リポジトリのセマンティックインデックス、自律的な experiment search はありません。静的ゲートにも依然として限界があります。