S2 的共用限流測試偶發失敗：兩次請求間隔量到 0.92 秒，斷言是 ≥ 0.95 秒

[kiki830621]

Problem

S2CommandTests.testTwoProcessesShareTheOneRequestPerSecondBudget 會偶發失敗：兩個 akashic 程序共用每秒 1 次的額度，測試斷言兩次請求的間隔 ≥ 0.95 秒，實測有一次是 0.92 秒。

2026-09-30 在一條只改 Sources/akashic-guards/ 的分支上跑全套，失敗 1 次；單獨跑這一支 3 次，失敗 1 次。那條分支沒有碰 S2 的程式，所以這是既有的不穩定。

Type

bug

Expected

• 先判斷 0.92 秒是量測誤差，還是限流本身真的讓兩次請求靠得太近。看 S2FileThrottle 預約時段的方式，以及測試怎麼量「請求送出的時間」：它量到的若是程序啟動或 stub 回應的時間，而不是 flock 預約之後的送出時間，就會有這種誤差。
• 限流正確：斷言改成量預約的時段，或把容差寫明並附理由。
• 限流不正確：修限流，測試不放寬。

Actual

全套測試偶爾因這一支紅燈。pre-push 跑全套，所以它也會偶爾擋下與 S2 無關的 push。

---

Source: #688／#689／#690 實作時的全套測試（2026-09-30）

---

Current Status

Phase: verified（R1 ensemble：沒有 HIGH；DA 對真的 S2FileThrottle 壓測，沒有找到小於 1.05 秒的間隔或飢餓）
Last updated: 2026-09-30 by idd-update

Blocking

• (none)——等你 /idd-close；單一呼叫者的吞吐量慢約 5%，代價已寫進 changelog，要改只保證間隔的做法請說

Commits

• cbc7d400（實作）
• 55b4b5b9（R1 修正：changelog 揭露）

[kiki830621]

Implementation Complete

#701：S2 跨程序限流測試偶發失敗。判斷結果是 issue 列的情形 (b)：限流本身真的會讓兩次請求相隔不到 1 秒。已修限流，測試斷言不放寬（仍是 ≥ 0.95 秒）。

• 已推上 main
• Commit：cbc7d400 fix: S2 節流醒來後在鎖內比對上一次實際放行，兩次請求的間隔才真的不小於 1.05 秒 (S2 的共用限流測試偶發失敗：兩次請求間隔量到 0.92 秒，斷言是 ≥ 0.95 秒 #701)

先量再改：量到的是什麼

測試量的是 loopback stub 收到請求的時刻。為了知道 0.92 秒是量錯時刻還是限流真的放太近，在 S2FileThrottle.acquire 與 S2Client.send 加了暫時的計時輸出（環境變數開啟、寫到 stderr、沒有 commit，量完用快照還原並 cmp 確認），跑這支測試 30 次，每個請求記下：預約的時段、醒來的時刻、放行的時刻、送出前的時刻、stub 收到的時刻。

量到的	結果
預約的時段兩兩相差	1.050 秒，180 次沒有例外
放行 → 送出前	0 ms
送出前 → stub 收到	1–5 ms
醒來比時段晚（Task.sleep 的晚醒）	睡約 1.05 秒的晚 124–139 ms；睡約 0.5 秒的晚約 58 ms
兩次放行的最小間隔	0.976 秒（30 次裡 2 次在 0.98 以下）
stub 收到的最小間隔	0.974 秒

結論：

• stub 收到的時刻與限流放行的時刻只差幾 ms，測試量的時刻沒有問題。不是 (a)。
• 放行的間隔＝1.05 秒＋後一個的晚醒－前一個的晚醒。前一個睡滿 1.05 秒、晚醒約 130 ms，後一個只睡約 0.5 秒、晚醒約 58 ms，間隔就是 0.976 秒。全套測試時負載更重，晚醒的差距更大，就到 0.92 秒。
• 預約只保證「每一次放行不早於自己的時段」，從來不保證兩次放行的間隔。spec Scenario「every pair of send times SHALL be at least one second apart, within a 50 ms tolerance」在負載下不成立。

改了什麼

• Sources/AkashicS2/S2Throttle.swift：acquire() 醒來後改呼叫新的 release()，在同一把 flock 鎖內決定：
  • 仍在 429 封鎖期 → 重新預約（原本 isBlocked() 的邏輯，併進來後刪掉 isBlocked()）；
  • 離上一次實際放行不到 1.05 秒 → 回傳還要等多久，睡完再問一次（不重新預約，保住自己的順位）；
  • 否則放行：狀態檔記下這一刻（新增可省略的 lastReleasedAt），並把 nextAllowedAt 推到至少這一刻加 1.05。
  • 小於 1 ms 的等待不睡（releaseSlack），所以保證的放行間隔是 1.049 秒。
  • lastReleasedAt 比現在晚超過 60 秒視為過期，與 nextAllowedAt、blockedUntil 同一條規則。
  • 比對在鎖內、等待在鎖外，spec 的「release the lock before waiting」照舊成立。
• Tests/AkashicCLITests/S2CommandTests.swift：跨程序測試的說明補一行 S2 的共用限流測試偶發失敗：兩次請求間隔量到 0.92 秒，斷言是 ≥ 0.95 秒 #701；斷言不動。
• openspec/changes/semantic-scholar-interface/design.md〈跨程序節流〉：狀態檔格式加 lastReleasedAt，補一條「放行間隔在鎖內保證」。spec 文字不必改。
• changelog/2026-09-30-s2-release-spacing.md。

沒有碰真的網路或 keychain：新測試用既有的假時鐘（FakeClock）與暫存狀態目錄；跨程序測試照舊走 loopback stub 與 akashic-test- 開頭的 keychain service。MCP 與 CLI 的輸出沒變，s2 status 報的下次可送時間讀的仍是 nextAllowedAt（放行時已把它推到實際放行加 1.05）。

測試

Tests/AkashicS2Tests/S2ThrottleReleaseSpacingTests.swift 三支：

1. testALateWakingPredecessorPushesTheNextReleaseBack：A 的時段 t0、晚 130 ms 放行；B 的時段 t0+1.05、準時醒 → B 多等 0.13 秒，不早於 t0+1.18 放行，共睡兩次。
2. testReleasePushesTheNextAllowedTimeFromTheActualRelease：放行後 peekNextAllowedAt 與下一個預約都從實際放行加 1.05 算起。
3. testAStaleLastReleaseDoesNotBlock：狀態檔的 lastReleasedAt 比現在晚 120 秒 → 不擋、不睡。

先寫測試時編譯不過（release() 還不存在）——這是這一輪的紅燈，行為上的紅燈由下面的負控給。修之後 S2 相關 55 支全綠。

負控（反向編輯，每次 cmp 確認還原）

反向編輯	結果
拿掉間隔比對	第 1 支紅（1.05 秒就放行、只睡一次）
拿掉 nextAllowedAt 的推移	第 2 支紅（1.05 ≠ 1.18）
拿掉 lastReleasedAt 的過期判斷	第 3 支紅（多睡 121 秒）
releaseSlack 改成 0	第 1 支在假時鐘上無限迴圈，手動中止。剩下約 1e-7 秒的等待小於 Date 在 t0 附近的解析度，假時鐘推不動。這是假時鐘的現象（真時鐘會前進，只會多睡一次極短的覺），但說明這個門檻不是裝飾

連跑的證據

PATH=/usr/bin:$PATH swift test --build-system native --skip-build --filter S2CommandTests/testTwoProcessesShareTheOneRequestPerSecondBudget，逐次執行，每次確認 Executed 1 test。機器上同時有其他工作（load average 約 13–17，18 核）。

	次數	失敗	最小間隔
修之前	20	2	失敗兩次的 0.935、0.945 秒
修之前，加計時輸出	30	0	stub 0.974 秒、放行 0.976 秒
修之後	20	0	（通過時測試不印時間）
修之後，加計時輸出	30	0	stub 1.047 秒、放行 1.050 秒；180 次放行裡 88 次多等了一次

全套測試：4333 支、1 skipped、0 失敗（這支跨程序測試 5.5 秒通過）。guards rc=0。

沒做的事

• 放行到封包送出之間的 client 開銷（實測 0–5 ms）不受限流控制，由 1.05 秒與 1 秒之間的 50 ms 餘裕吸收。沒有辦法在不持有鎖跨越網路請求的前提下再縮小它，spec 也要求等待時不持鎖。
• 舊 binary 寫回狀態檔時會丟掉 lastReleasedAt（JSONEncoder 只寫它認得的欄位）。新舊 binary（例如還沒更新的 akashic-mcp）同時在跑時，那一次的間隔回到只由預約保證。
• 沒有調整 Task.sleep 的容許誤差。縮小晚醒只能讓間隔少縮一點，負載重時仍會縮，所以改在鎖內比對。
• 「修之前 20 次失敗 2 次」是一個小樣本；加計時輸出那 30 次沒有失敗、只量到 0.974 秒，說明失敗與否取決於當下的負載。修之後的保證來自鎖內比對的邏輯與負控，不來自這幾十次沒失敗。
• 沒有跑 idd-verify。

[kiki830621]

Verify R1（#701）

這一輪

六席：requirements、logic、security、regression、devil's advocate、Codex。全輪 44 則：HIGH 0、MEDIUM 6、LOW 23、INFO 15。logic、regression、devil's advocate 三席第一次因網路錯誤失敗，從快取重跑。

屬 #701 的：LOW 1（第 13 則）、INFO 3（第 30、37、42 則）。Codex 對 #701 沒有報告（第 29 則）。沒有席找到實作缺陷：DA 席以真的 S2FileThrottle 壓測三種情境，最小放行間隔 1.051–1.052 秒、沒有飢餓。

修正 commit：55b4b5b9（只改 changelog 與一行 doc comment，行為不變）。

逐則處置

則	席	嚴重度	內容	處置
13	logic	LOW	放行時推 nextAllowedAt，單一呼叫者吞吐量降約 5%，changelog 未揭露；另「50 ms 餘裕」與測試的 0.95 秒門檻對不上	修（55b4b5b9）：changelog 補一節——logic 席實測 1.101 對 1.056 秒、DA 席 64 程序平均 1.10 秒，重負載下更多；接受的理由：額度是外部的每秒 1 次，放得太早是 429 與封鎖期、放得太晚只是延遲，慢的方向是安全的一側；不推 nextAllowedAt 也保證得了間隔，但下一個呼叫者照推理會醒來再睡一次（這一點沒有量）；要改回來的條件是出現吞吐量真的不夠用的流程。餘裕改寫成「對 1 秒名目值 49 ms、對 0.95 秒門檻約 99 ms」。S2FileThrottle.release() 的 doc comment 補一行代價
30	requirements	INFO	修法站得住；餘裕與 20/20 的統計強度	餘裕同第 13 則；統計強度不動（機制與單元測試承擔論證）
42	devil's advocate	INFO	壓測未找到違反；吞吐降約 5% 屬實	採納，數字寫進 changelog
37	security	INFO	#701、#702 安全面無發現	不動

待裁

吞吐量的代價現在是有記錄的取捨。使用者若認為連續查詢的延遲不值得，可以改成只保證間隔、不推 nextAllowedAt（第 13 則 logic 席的建議），要先量一次多睡一次的比例再決定。