Test: backward-compat numeric-string chat_id / from_message_id parsing

[kiki830621]

Problem

HandlerArgs.swift 的 int64ArgValue helper 保留了舊 handler 的行為——除了 .int(...) 外也支援 .string("123") 形式的數字字串：

private func int64ArgValue(_ args: [String: Value], _ key: String) -> Int64? {
    guard let value = args[key] else { return nil }
    if let n = value.intValue { return Int64(n) }
    if let s = value.stringValue { return Int64(s) }
    return nil
}

但 ServerHandlerLogicTests 沒有測這條 backward-compat 路徑。

From verification of #7 by Codex:
「舊 handler 支援數字字串形式的 chat_id / from_message_id，新 helper 也保留了這個行為，但目前測試沒有明確覆蓋這條相容性。」

Type

enhancement

Expected

加 test case 驗證：

• {"chat_id": .string("100")} → chatId == 100
• {"from_message_id": .string("12345")} → fromMessageId == 12345
• {"chat_id": .string("not-a-number")} → throws (required field invalid)

避免未來有人重構 int64ArgValue 時不小心拿掉 string fallback。

Code Reference

• Sources/CheTelegramAllMCPCore/HandlerArgs.swift:72-78

Related: #7

---

Current Status

Phase: closed
Last updated: 2026-04-27 by idd-close

Key Decisions

• 4 個 tests（plan 寫 3，加 dump parity 1）
• .string("not-a-number") 走 silent → nil → required-field 路徑（int64ArgValue 設計）— DA 反駁 misleading message，opened follow-up chat_id type-mismatch error message misleads (silently shows 'is required' instead of type error) #22 修 UX
• 6-AI verify: PASS

Scope Changes

• +1 dump parity test（testDumpChatIdAsStringAccepted）

Blocking

(none)

Test counts

• 156 → 160 (+4) → 163 after MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify-DA fix
• All pass
• Codex independent: 34 ServerHandlerLogicTests pass

Commits

• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)

Follow-up

• chat_id type-mismatch error message misleads (silently shows 'is required' instead of type error) #22 — chat_id type-mismatch error message misleads (DA F4)

[kiki830621]

Diagnosis

Type

enhancement (backward-compat test)

Analysis

int64ArgValue helper 對 chat_id / from_message_id 接受 .int(n) 和 .string("123") dual-path，但 ServerHandlerLogicTests 沒覆蓋 .string 路徑。未來若有人 refactor int64ArgValue 拿掉 string fallback，沒 test 抓得到。

Strategy

加 unit tests 鎖 int64ArgValue 的 backward-compat 行為：

• .string("100") → chatId == 100
• .string("12345") → fromMessageId == 12345
• .string("not-a-number") → throws (chat_id required field invalid)
• 對 dump parser 的 chat_id 也加同樣 test

Complexity

Simple — 純 test addition，無 source code 變更。

---

Implementation Plan

Phase 1: Add backward-compat tests

• testChatIdAsStringAccepted — get_chat_history .string("100") → chatId == 100
• testFromMessageIdAsStringAccepted — .string("12345") → fromMessageId == 12345
• testChatIdAsStringInvalidThrows — .string("not-a-number") → throws "chat_id is required"
• testDumpChatIdAsStringAccepted — dump_chat_to_markdown parity

Phase 2: Verify

• swift test --skip E2ETests: all green
• CHANGELOG entry under same [0.5.3] Test section

Commit strategy

1 atomic commit (test-only).

Scope check

✅ 純 test addition，對應 issue Expected。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

Phase 1: Add backward-compat tests

• testChatIdAsStringAccepted — .string("100") → chatId == 100
• testFromMessageIdAsStringAccepted — .string("12345") → fromMessageId == 12345
• testChatIdAsStringInvalidThrows — .string("not-a-number") → throws "chat_id is required"
• testDumpChatIdAsStringAccepted — dump_chat_to_markdown parity

Phase 2: Verify

• swift test --skip E2ETests: 156 → 160 (+4) all green
• CHANGELOG entry under [0.5.3] Test section

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)

Changes

• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Files Changed (#12 scope)

 ServerHandlerLogicTests.swift  | +39 (4 tests under "MARK: - #12 backward-compat" section)
 CHANGELOG.md                   | (covered in 0.5.3 Test section)

Test counts

• Before: 156 tests
• After: 160 tests (+4)
• All pass

Insight

testChatIdAsStringInvalidThrows 揭露 int64ArgValue 的優雅 fallback 設計：.string("not-a-number") 不會 throw type error，而是 silently 回 nil → required-field 路徑接手 throw "chat_id is required"。這跟 #8 A1 對 max_messages 的 strict reject 路徑不一樣（max_messages 改成 Int 失敗就 throw "must be an integer"）。差異原因：chat_id 是 required field，type fail 走 missing-field 路徑語意更清楚；max_messages 是 optional，type fail silently fallback 才是過去 bug 根源。

Scope Compliance

所有改動限於 ServerHandlerLogicTests.swift（test-only addition）。

Next: verification pending

[kiki830621]

Verify: Batch 3 (#8 + #11 + #12 + subsumed #20)

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.5 xhigh) = 6-AI review

要求覆蓋率

• MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 4/4 sub-requirements addressed (FULLY) — type enforcement + DateParsing→TelegramAllLib + CLI parity + --until end-of-day
• Test: assert MCP handler error message text (contract test) #11 1/1 (FULLY in named cases; PARTIALLY if literally "all throws-tests") — 7 contract assertions on key tests
• Test: backward-compat numeric-string chat_id / from_message_id parsing #12 3/3 sub-requirements addressed (FULLY) + 1 dump parity test
• max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed: .string + .double rejection now correctly distinguishes type-error vs cap-error after DA fix

Findings（合併去重，按 severity 排序）

#	Severity	Finding	Source	Action
1	—	Behavior 100% equivalent for legitimate .int callers; truth tables verified across 14 cases (logic) and 24 tests pass independently (codex)	team:logic + codex	PASS
2	—	Scope check passed: only 6 files touched, 21 existing DateParsingTests still green after internal → public move	team:regression + codex	PASS
3	—	Visibility expansion (DateParsing → public in TelegramAllLib) is benign — pure parse, no FS/network	team:security	PASS
4	—	validateMaxMessagesCap shared helper continues to be security-positive (single source of truth for cap policy)	team:security	PASS
5	HIGH	parseMaxMessages rejected .double(5000.0) as type-mismatched, but JSON spec allows whole-number doubles. MCP SDK already provides Int(value, strict: false) (Value.swift:320) which uses Int(exactly:) to coerce whole-number doubles correctly. DIY dual-path missed this. In-scope fix f0203ac — replaced 8-line custom logic with single SDK call.	team:devils-advocate	In-scope fix ✓
6	MEDIUM	CLI ValidationError("--since \(e.description)") produces grammatically broken "--since Date format invalid: ..." (reads like flag is named --since Date). In-scope fix 2a05f83 — restored old phrasing "--since must be YYYY-MM-DD; got X" by extracting DateParseError.input directly.	team:devils-advocate	In-scope fix ✓
7	MEDIUM	testChatIdAsStringInvalidThrows asserts "chat_id is required" for .string("not-a-number"), but the field IS provided (just type-mismatched). Inconsistent with max_messages's strict "must be an integer". UX bug.	team:devils-advocate	Follow-up
8	MEDIUM	parseDumpChatToMarkdownArgs default 5000 no longer goes through validateMaxMessagesCap (only when key absent). Currently safe (5000 < 10_000) but if cap policy changes to 1000, default would silently bypass.	team:devils-advocate + logic LOW informational	Follow-up
9	MEDIUM	Exact-match contract tests (#11) lock cap value 10_000 and suggestion text. Cap policy change requires synchronized N-test update. Plan said hasPrefix; implementation chose exact.	team:devils-advocate	Follow-up
10	MEDIUM	Server.swift other numeric option args (limit ?? 50/20/200 at lines 374, 387, 446, 454) still have same silent-fallback pattern that #8 A1 fixed for max_messages. Only half-fixed.	team:devils-advocate	Follow-up
11	LOW	Phase 1 commit a918b11 is "dirty checkpoint" (parseMaxMessages exists but DateParsing still in MCPCore, CLI still inline). Repeat of #13 a834e88 anti-pattern. Third occurrence now.	team:devils-advocate	Won't fix (already past bisect window; future batches should squash phases)
12	LOW	#20 subsume is "ahistorical revisionism" — #8 original scope didn't include .double; expanded after DA finding.	team:devils-advocate	Won't fix (commit message + closing comment of #20 leave full audit trail)
13	LOW	CHANGELOG 0.5.3 mixes 4 issues (#8/#11/#12/#20) in one minor version. Users can't cherry-pick individual fixes.	team:devils-advocate	Won't fix (release cadence preference; can split future)
14	LOW	ServerHandlerLogicTests.swift now 426 lines (CLAUDE.md "200-400 typical"). Trajectory: #7 ~170, #13 ~290, #8/#11/#12 ~430. Approaching 500.	team:devils-advocate	Follow-up
15	LOW	testTarget doesn't explicitly depend on TelegramAllLib in Package.swift (works via transitive); CLI's parseCLIDate wrapper has no direct CLI integration test (relies on underlying 21 DateParsingTests)	team:regression	Won't fix (transitive deps + thin wrapper coverage adequate)

Devil's Advocate 反駁有效率

DA 反駁 4 reviewer + Codex 的「全 PASS」判定，找出 2 個 HIGH (F1+F2 = #5) + 4 MEDIUM + 2 LOW–MEDIUM + 3 LOW。

• 2 個 in-scope fix 已修（日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5/max_messages 邊界防護: 加硬上限 + 0/負數處理 #6，commits f0203ac + 2a05f83）
• 4 個 follow-up（MCP 層補 handler 行為 unit test（get_chat_history） #7/MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/改善 stderr log 格式: ASCII 箭號 + DateParseError internal visibility #9/Input hardening: DateParseError input truncate + since/until range sanity check #10 + Test: handler glue integration (errorResult conversion + tdlib wiring) #14）
• 3 個 won't fix（Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12/Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 + Test hardening: int64 helper DRY + boundary + TZ assertions #15，理由透明）

集體盲點被精準抓到：4 reviewer + Codex 都默認「strict reject .double 是 fix bug」，沒人翻 SDK 找 lenient API。Codex 雖驗證 5000 decode 成 .int(5000)，但漏了「caller 主動傳 5000.0」這條 cross-language ABI 路徑。

Codex 獨立貢獻

• 跑 swift test --filter ServerHandlerLogicTests (34 tests pass) + --filter DateParsingTests (14 tests pass) 自驗
• 直接讀 swift-sdk Value.swift Codable decode order，確認 JSON 5000 decode 成 .int(5000)（不是 .double(5000.0)）
• 點出 Test: assert MCP handler error message text (contract test) #11 嚴格解讀為 PARTIALLY（dump 的 throws tests 沒升級到 exact match — 可作為 Test: assert MCP handler error message text (contract test) #11 follow-up）

Scope Check

PASS — 改動限於 6 檔案（HandlerArgs / DateParsing / Server / TelegramAllCLI / 2 tests / CHANGELOG），全部追溯 #8/#11/#12/#20。F1+F2 + F3 in-scope fix 不擴大 scope，反而糾正原始實作的 over-correction。

Tests

• 150 → 163 tests pass, 0 failures
• Codex 獨立驗證 swift test 通過（34 + 14 = 48 隔離 filter tests）

Commits

• a918b11 fix: enforce max_messages type, reject string/double silent fallback (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, max_messages silently falls back to default for .string/.double values (cap bypass) #20)
• b7e7899 fix: CLI date parity with MCP — share parseISODate/parseUntilDate (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8)
• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed
• f0203ac fix: accept whole-number .double via MCP SDK Int(value, strict:false) (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F1+F2)
• 2a05f83 fix: CLI date error message reuses old phrasing (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F3)

判決

PASS — 無 blocking findings 留存；2 個 HIGH/MEDIUM in-scope 已修復（f0203ac + 2a05f83）；5 個 valid follow-ups（#7/#8/#9/#10/#14）待 user triage；3 個 informational won't-fix 理由透明。

[kiki830621]

Closing Summary

Problem

#7 verify 階段 Codex 點出：int64ArgValue helper 對 chat_id / from_message_id 接受 .int(n) 和 .string("123") dual-path（為 backward-compat 給用 JSON 引號包整數的 caller），但 ServerHandlerLogicTests 完全沒覆蓋 .string 路徑。未來若有人 refactor int64ArgValue 拿掉 string fallback，沒 test 抓得到，舊 caller 會 silently break。

Root Cause

• int64ArgValue 的 dual-path 是 歷史設計（早期 MCP client 慣例 quote 數字 in JSON）
• 該 helper 一直只在 parseGetChatHistoryArgs / parseDumpChatToMarkdownArgs 內部被使用，外部沒 test driver 直接驗證 backward-compat
• Test 寫法習慣是 chat_id: .int(100) — 沒人想到 caller 可能傳 .string("100")

Solution

加 4 個 unit tests（plan 寫 3，加 dump parity 1）鎖 backward-compat：

Test	Behavior
testChatIdAsStringAccepted	.string("100") → chatId == 100
testFromMessageIdAsStringAccepted	.string("12345") → fromMessageId == 12345
testChatIdAsStringInvalidThrows	.string("not-a-number") → throws "chat_id is required"（silent fallback to required-field path）
testDumpChatIdAsStringAccepted	dump_chat_to_markdown parser parity

Architectural insight：testChatIdAsStringInvalidThrows 揭露 int64ArgValue 的 fallback 設計 — .string("not-a-number") 走 silent → nil → required-field 路徑接手 throw "chat_id is required"，跟 #8 A1 對 max_messages 的 strict reject（throw "must be an integer"）不同。差異原因：chat_id 是 required field（type fail 走 missing-field 路徑語意可接受），max_messages 是 optional with bug history（type fail strict reject 才能避免 silent fallback）。

Verification

Engine：5 Claude reviewers + Codex = 6-AI。

維度	Result
3/3 reqs (chatId / fromMessageId / invalid string)	FULLY
Dump parity (+1 scope creep, transparent)	FULLY
Test count 156 → 160 (+4) → 163 after #8 verify-DA fix	PASS
Codex 獨立驗證	34 ServerHandlerLogicTests pass

DA 反駁 misleading message（MEDIUM）：testChatIdAsStringInvalidThrows 鎖了 "chat_id is required" 訊息，但使用者有提供 chat_id，只是 type 錯了。訊息誤導 debug — 與 parseMaxMessages 對 .string("not-a-number") 的 strict "must be an integer" 訊息不對稱。Follow-up #22 處理 UX 修正。

Changes

• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Follow-up

• chat_id type-mismatch error message misleads (silently shows 'is required' instead of type error) #22 — chat_id type-mismatch error message misleads (DA F4)