food_chain/IMPLEMENTATION-NOTES.md

# 実装記録 — v45 free movement

## v45 モジュール整合性修正

- `engine.js` が要求する `fieldResourceIntakeKgPerDay` は `ecology/feeding.js` に実在する。
- v44 は entry module だけに版クエリが付き、依存モジュールが無版指定だったため、ブラウザキャッシュで旧 `feeding.js` と新 `engine.js` が混在し得た。
- v45 は production の相対 `.js` import と Worker URL をすべて `?v=45` に統一した。
- 回帰テストは 58 行のスモークテストへ縮小し、モジュール契約・自由移動・水域編集・短期出生・削除済み機能の再混入だけを確認する。長期較正や文献式の確認は `VALIDATION.md` に分離する。

## 目的

v43 で残っていた以下の移動不具合を、スポーン地点への拘束や症状検出型補正を使わずに修正する。

- 個体がほとんどスポーン地点から離れない
- 微動だにしない個体が多い
- 岸線や資源目標付近で往復振動する
- home-range を完全に削除する

## 1. home-range の完全削除

削除した状態/処理:

- home point (`homeX`, `homeY`)
- home radius
- profile別 home-range multiplier
- スポーン地点へ戻す steering
- home-range を用いた daily movement 計算

動物は現在位置から自由移動 waypoint を生成する。複数 waypoint を経由するため、開始地点を中心とする空間拘束はない。

## 2. 初期配置

非両棲個体は、指定された生成中心が不適切でも単に岸線ぎりぎりへ押し出さない。

`make()` は個体半径を考慮した岸線 clearance を満たす有効 habitat を探索して初期位置を決める。これにより、開始直後から habitat boundary clipping を繰り返す条件を除去した。

## 3. 岸線での連続 steering

左右の候補角を交互に試す方式は使用しない。

岸線近傍では signed-distance field の勾配から legal habitat 側の法線を求め、希望進行方向のうち禁止 habitat へ向かう成分だけを除く。残った接線成分で岸に沿って進む。

この方式は「振動を検出して止める」のではなく、禁止方向へ向かう速度成分を幾何学的に除去する。

## 4. persistent free-roaming waypoint

短いランダム微動ではなく、daily movement capacity から距離を抽選した waypoint を保持する。

- waypoint は現在位置から生成
- habitat を横切る直線経路は候補から除外
- 到達すると次 waypoint を生成
- 移動不能になった waypoint は破棄して再計画
- world edge 到達時も再計画

開始地点を記憶していないため、徘徊範囲は日ごとに空間上を移動できる。

## 5. producer / zooplankton 目標の往復除去

continuous field の資源点は実在する個体ではない。到達後も同じ仮想点を追跡すると、roaming と資源点追跡が切り替わり往復する。

v45 は feeding envelope に入った時点で仮想 target を破棄し、field density から摂食しながら roaming を続ける。

## 6. stamina

旧方式では sprint 消費と回復の単位スケールが釣り合わず、数日規模の休息が発生し得た。

v45:

- routine movement: sprint stamina を消費しない
- chase / escape: stamina capacity に対する割合で消費
- rest: capacity に対する割合で回復
- 通常活動中も少量回復

これにより大きな stamina pool を持つ個体だけ回復に極端に長時間かかることを避ける。

## 7. 群れ制御

social steering は位置のみを入力とする。

- separation
- 弱い centroid cohesion

近隣個体の速度 alignment は使わない。回転指数、角運動量、逆トルク等を production runtime で検出・補正する処理もない。

## 8. 維持した仕様

- day / m / kg / kJ
- `DT = 1/24 day`
- 水深なし
- 人為的攪乱なし
- experiment/batch API なし
- 詳細診断出力なし
- user-edited water geometry はそのまま
- 初期 procedural water のみ `radius × sqrt(2)`
- 厳密2倍化アルゴリズムなし
- 通常表示 `×1` target = 1 simulated day / real second

検査結果は `VALIDATION.md` に記録する。