fix(poller): add a run-wide subrequest budget to the wiki surface [poller, docs, tests]

[smileygames]

Closes #248

何が壊れていたか

wiki surface の予算はすべて repo 単位で、run 全体の総和を見る主体がいなかった。wiki cron は 1 invocation で POLL_REPOS を全て歩くため、各 repo が個別には規約を守る一方で総和が Cloudflare の invocation 上限を超え、枯渇を最後尾の repo だけが一身に受けていた。枯渇は loop の性質であって、その repo の性質ではない。

変更点

run 全体の予算. WIKI_SUBREQUEST_BUDGET_PER_RUN を新設し、runWikiSurfaces が各 pass の実測消費を差し引きながら repo を歩く。除算ではなく減算 — diff surface の diffFileBudgetPerPhase が除算なのは phase の費用が事前に確定するからで、wiki の走査費用は走らせてみるまで分からない。おかげで変更の無かった repo は取り分をほぼ丸ごと後続へ渡す。既存の repo 単位予算は維持し、その上に被せる形（置き換えではない）。

枯渇時は failed を記録しない. 残予算が pass を賄えない repo は呼び出し自体を行わない。cursor は据え置かれ、次の run が同じ page から再開する。liplus-language が既に示していた「上限に達したら cursor を残して正常終了」を run 全体の軸へ持ち上げた形。

観測した miss と観測していない miss の分離. WikiPollSummary に subrequests と inconclusive を追加。probe が例外を投げた page は絶対に「404 を観測した」ことにならないので inconclusive に計上し、failed から分離した。No content fetched ... (all candidates 404) の誤誘導的な文言を、例外と本物の 404 が区別できる 2 つの文言に置き換えた。inconclusive でも cursor は前進させる（留めると恒久的に到達できない page 1 つが walk 全体を停止させうるため）。

処理順の公平性（issue が判断を求めていた点）. 入れることにした。固定順のままだと痩せるのは毎 cron 同じ最後尾で、溢れだけを止めても「結果を決めるのは loop 上の位置」という元の欠陥の形がそのまま残るため。rotateReposForRun が tick ごとに走査順をずらす。offset は scheduledTime から導出するので watermark も schema 変更も不要で、同じ tick に対しては決定的（= テスト可能）。

取り分の値について（レビュー時に見てほしい点）

定数は call site から読み取った会計単位であり、Cloudflare の課金単位ではない。この会計では、失敗した run は 6 番目の repo が例外を投げた時点で消費約 300 であり、文書化された上限 1000 には届いていない。差は poller 側から見えるもので説明できないため、少なくとも 1 つの binding がこの会計の 1 より高く課金されている（どれが・どれだけかは未計測）。

したがって取り分は、唯一手元にある硬い観測 —— その run はこの単位で 300 未満で枯渇した —— に対して較正し 250 とした。文書化された 1000 に合わせると、この単位では到達不能な値になり、上限が永久に発火しない（= 修正にならない）。DIFF_SUBREQUEST_BUDGET_PER_RUN が 900 なのは diff surface の per-file 見積もりが実測された reject に対して導出されているからで、この surface にはその導出が無い以上、その数値の確度は借りていない。

低く取る代償は latency で、最も安い場所で支払われる: 先送りされた repo は cursor から再開し、費用の高い pass は元々複数 run に跨がる bulk import であり、索引済みの wiki は hash 比較で止まって embed の fan-out に到達しない（定常状態では全 repo が満額歩く）。

poller.ts と docs に残っていた invocation budget of 1000 を前提とした安全性の主張も、宣言した取り分を参照する形に直した。

テスト

src/poller-wiki.test.ts に 10 件追加（合計 36 件、全体 290 + 70 件 pass）。

• 本番と同じ 6 repo 構成（page 数 5 / 7 / wiki 無効 / 87 / 5 / 12）の fixture で、どの repo も failure を記録しない。歩かれなかった repo は cursor 未変更であることを確認。Too many subrequests がログに一切現れない。空振り防止のため「3 つ以上の repo が実際に歩かれたこと」も表明している
• run 全体の予算が repo 単位予算より優先される（残予算が薄いと fetch 上限が repo 単位定数を下回る）
• 予算を賄えない repo は呼び出されず、cursor が据え置かれる。先送りは常に走査順の末尾側で、途中に穴が空かない
• 先送りされた repo が後続の tick で先頭側に回り、1 周以内に必ず歩かれる
• 例外による miss は inconclusive、404 を観測した miss は failed（両方向）
• 87 page の wiki の複数 run 消化が破綻していない（5 run で全 page 到達）
• 処理順の回転が list を変えず、N tick で全 repo が 1 度ずつ先頭に立つ

CI 相当をローカルで全て通過: npm test / npx tsc --noEmit / node scripts/check-schema-drift.mjs / npx wrangler deploy --dry-run。

要件記述

docs/0-requirements.md / docs/0-requirements.ja.md を同一 PR で更新。

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	github-rag-mcp	90355f8	Aug 15 2026, 05:59 AM

[smileygames]

AI self-review (execution mode: auto) — 2 回目、pass

1 回目の self-review で 1 件指摘し、差し戻した。実装者は ACCEPT で adjudicate し、90355f8 で改訂済み。

指摘の帰結

指摘: 宣言された share (250) は定常運転のプロファイルでは発火せず、issue #248 の受け入れ条件 1 が満たされない。

改訂の方向は「予算を下げる」ではなく 「予算では直せないと結論し、枯渇の実行時検知を足す」 だった。この判断を支持する。予算の較正が不可能である理由（Workers に実行時カウンタが無い）は事実として確認でき、観測された 1 点に定数を合わせるのは同じ誤りの反復になる。

なお実装者は「全リポジトリが 0 embedded だった」という私の前提に、issue 本文からは裏付けられないという留保をつけ、保守側の幅（約 70〜292）で再計算して同じ結論に至っている。留保は正しい — 表から embedded 欄を落としたのは私の側の欠落である。事実としては tail ログに全リポジトリ 0 embedded が記録されており、実際の消費は下端（約 70〜98）に寄る。結論は変わらず、実装者の取った幅の方が保守的である。

検証したもの

項目	結果
枯渇時に cursor が動かない	pass — break は nextCursor = page.slug の前に置かれている
枯渇時に reap が省略される	pass — listIndexedWikiPages の D1 呼び出し自体を回避
枯渇後に後続リポジトリが未接触	pass — hitTheWall で continue、pollWiki を呼ばない
hitTheWall が false に戻らない	pass — true 以降は先頭で continue するため代入に到達しない
通常の network error と識別される	pass — isSubrequestExhaustion で分岐、per-page 軸に留まる
reap probe 側の枯渇検知	pass — continue 後、次反復先頭の break で追加 probe なし
runWikiSurface の catch 経路	pass — summary を経ずに throw した枯渇も run を終了させる
受け入れ条件の改訂	pass — issue #248 本文で原文を取り消し線で残し、達成可能な形へ改訂済み

特に評価する点

否定的結果を回帰テストで固定したこと。 does not engage the declared share on the observed steady-state run は「この予算はこの形には効かない」ことを pin するテストである。将来これが落ちたら、単位のズレが解消したか費用モデルが壊れたかのどちらかであり、どちらも停止に値する。守っているように読める定数を黙って残さない、という当初の要求に対する最も誠実な応答である。

stubMultiWiki の throw メッセージが枯渇文言のままだと新しい分岐に吸われて inconclusive の検証が空回りする、という自己申告も適切だった。

scope 逸脱

なし。rotation は issue が実装側の判断に委ねた項目であり、判断理由は記録されている。

次のステップ

auto モードにつき人間レビュー不要。self-review pass により直接 merge する。merge 後は Workers Builds の自動 deploy を経て、次の 45 * * * * tick が実地の観測点となる。観測すべきは Too many subrequests の消失ではなく、1 回の拒否が偽の page failure の連鎖に変わらないことである。