thth 2.4.0__tar.gz → 2.5.0__tar.gz

{thth-2.4.0 → thth-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thth
-Version: 2.4.0
+Version: 2.5.0
 Summary: 承認済みの投稿だけを投げる門（Threads・Bluesky・Mastodon）。人が承認し、記録は利用者の git に残る。
 Project-URL: Homepage, https://thth.me
 Project-URL: Source, https://github.com/aokings/thth
@@ -33,7 +33,7 @@ watchtower（`~/Developer/watchtower`）の隣に同じ流儀で並べる。watc
 
 ## 版
 
-このソースの版は **2.4.0**。現在の設計は [自分の泉](docs/設計_自分の泉_2026-09-16.md)、導入は [自分の Meta アプリで動かす](docs/導入_自分のMetaアプリで動かす.md)、文書の索引は [docs/README.md](docs/README.md)。
+このソースの版は **2.5.0**。現在の設計は [自分の泉](docs/設計_自分の泉_2026-09-16.md)、導入は [自分の Meta アプリで動かす](docs/導入_自分のMetaアプリで動かす.md)、文書の索引は [docs/README.md](docs/README.md)。
 
 版の正本は `thth/VERSION`（`server.json` はテストで一致を強制）。開発中の `main` には未配布の変更も含まれます。インストール済みの版は `thth --version`、VM の版と revision は `thth board` で確認してください。
 
@@ -45,7 +45,7 @@ watchtower（`~/Developer/watchtower`）の隣に同じ流儀で並べる。watc
 
 ## 実装と運用の状態（2026-09-18）
 
-2.4.0 の実装 revision の全件テストは **2452 件**（`python -m pytest tests/ -q -n auto -p no:cacheprovider`・1 skip・rc=0）。開発中の変更の検証は対象 revision の CI を参照してください。
+2.5.0 の実装 revision の全件テストは **2690 件**（`python -m pytest tests/ -q -n auto -p no:cacheprovider`・1 skip・rc=0）。開発中の変更の検証は対象 revision の CI を参照してください。
 
 **媒体**: Threads（稼働）・Bluesky・Mastodon（同席用の台帳あり・未稼働）。
 
@@ -59,6 +59,13 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 
 **トピックの棚**（`thth topics`）: 観測者ごとに並ぶ・打ち消し `retract-note`・`history`。
 
+### v2.5.0 の変更
+
+- 読み取り専用のレポート 3 本: `analytics-report`（活動のスナップショット・`--compare-previous` で隣接期間の比較）・`handoff-report`（ローカル運用記録の引継ぎ）・`study-report`（施策の宣言と本人の観測の結合）。MCP に `analytics_report`・`operations_handoff`・`study_report`。数値は期間・母数・欠測・根拠を連れて歩き、因果や推奨は出しません。
+- `serve-reports`: 専用環境向けの非公開レポート HTTP（Unix socket 既定・service credential・読むだけ）。**開発版**で、人の認証・TLS・一般提供は含みません。[限界](docs/非公開レポートHTTP_v1.md)。
+- X の本人公開指標の純粋な変換関数（API・投稿・台帳には未接続）。
+- 独立監査（P2 4・P3 7）とその直し: Unix socket 既定・要求全体の 10 秒 deadline・分離検査の走査を読取 dir に限定・期間比較の母集団から時刻不一致の返信を除外・git 無しでも import 可。
+
 ### v2.4.0 の変更
 
 - 利用者・管理者への停止／復旧メールと、元原稿の運用記録。設定・秘密は repo 外に保存します。導入時は [共通通知手順](docs/停止通知と運用記録.md) を実施します。
@@ -87,7 +94,7 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 - **英語の文書**: [README.en.md](README.en.md)・[docs/usage.en.md](docs/usage.en.md)・[llms.txt](llms.txt)。
 - **skill**: `skills/thth/SKILL.md`（wheel にも入る）。
 
-- **動くもの**（`thth --help` の全 36 サブコマンド）: `lint`・`preview`・`approve`・`account`・`revoke`・`posts`・`replies`・`measured`・`threads`・`after`・`topics`・`forms`・`queue`・`schedule`・`throw`・`run`・`systemd`・`board`・`collect`・`pull`・`auth`・`refresh`・`maintain`・`send`・`doctor`・`app`・`token`・`ask`・`mentions`・`profile`・`thread`・`where`・`who`・`retract`・`location`・`notifications`。
+- **動くもの**（`thth --help` の全 40 サブコマンド）: `lint`・`preview`・`approve`・`account`・`revoke`・`posts`・`replies`・`measured`・`threads`・`after`・`analytics-report`・`study-report`・`handoff-report`・`serve-reports`・`topics`・`forms`・`queue`・`schedule`・`throw`・`run`・`systemd`・`board`・`collect`・`pull`・`auth`・`refresh`・`maintain`・`send`・`doctor`・`app`・`token`・`ask`・`mentions`・`profile`・`thread`・`where`・`who`・`retract`・`location`・`notifications`。
 - **最初の本番投稿の記録**: 2026-09-09、@aoking に疎通確認を 1 本（`17916074118445631`）。
 - **未着手**: X・Facebook ページ・Instagram の各アダプタ。トピック検索の権限（tester には降りない）。泉のサーバ（v2-5）。
 - **権限の制約**: tester に降りる scope は 5 つ。削除はできない。
@@ -98,3 +105,12 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 registry は「この PyPI の名前を名乗ってよいのは誰か」を、**配布物の README にこの 1 行があるか**で確かめる（設計 v2-4 §3・一次資料は quickstart・**L2**）。だから消さないこと——消すと登録（`mcp-publisher publish`）が通らなくなる。形（`server.json` と版の一致）は `tests/test_server_json.py` が見張る。
 
 mcp-name: io.github.aokings/thth
+
+## v3 基盤（2.5.0 から）
+
+`study-report` は明示した施策の宣言と本人の投稿観測を結ぶ読み取り専用レポートです。採用者の本人確認や因果効果は主張しません。[使い方と契約](docs/施策レポート_v1.md)。
+
+`analytics-report` はローカル台帳から期間・母数・欠測・根拠を揃えたスナップショットを返します。
+[形式と使い方](docs/分析レポート_v1.md)。
+
+`handoff-report` / MCP `operations_handoff` はローカル運用状態・通知未処理を鮮度の制約付きで返します。[形式と使い方](docs/運用引継ぎレポート_v1.md)。

{thth-2.4.0 → thth-2.5.0}/README.md

@@ -9,7 +9,7 @@ watchtower（`~/Developer/watchtower`）の隣に同じ流儀で並べる。watc
 
 ## 版
 
-このソースの版は **2.4.0**。現在の設計は [自分の泉](docs/設計_自分の泉_2026-09-16.md)、導入は [自分の Meta アプリで動かす](docs/導入_自分のMetaアプリで動かす.md)、文書の索引は [docs/README.md](docs/README.md)。
+このソースの版は **2.5.0**。現在の設計は [自分の泉](docs/設計_自分の泉_2026-09-16.md)、導入は [自分の Meta アプリで動かす](docs/導入_自分のMetaアプリで動かす.md)、文書の索引は [docs/README.md](docs/README.md)。
 
 版の正本は `thth/VERSION`（`server.json` はテストで一致を強制）。開発中の `main` には未配布の変更も含まれます。インストール済みの版は `thth --version`、VM の版と revision は `thth board` で確認してください。
 
@@ -21,7 +21,7 @@ watchtower（`~/Developer/watchtower`）の隣に同じ流儀で並べる。watc
 
 ## 実装と運用の状態（2026-09-18）
 
-2.4.0 の実装 revision の全件テストは **2452 件**（`python -m pytest tests/ -q -n auto -p no:cacheprovider`・1 skip・rc=0）。開発中の変更の検証は対象 revision の CI を参照してください。
+2.5.0 の実装 revision の全件テストは **2690 件**（`python -m pytest tests/ -q -n auto -p no:cacheprovider`・1 skip・rc=0）。開発中の変更の検証は対象 revision の CI を参照してください。
 
 **媒体**: Threads（稼働）・Bluesky・Mastodon（同席用の台帳あり・未稼働）。
 
@@ -35,6 +35,13 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 
 **トピックの棚**（`thth topics`）: 観測者ごとに並ぶ・打ち消し `retract-note`・`history`。
 
+### v2.5.0 の変更
+
+- 読み取り専用のレポート 3 本: `analytics-report`（活動のスナップショット・`--compare-previous` で隣接期間の比較）・`handoff-report`（ローカル運用記録の引継ぎ）・`study-report`（施策の宣言と本人の観測の結合）。MCP に `analytics_report`・`operations_handoff`・`study_report`。数値は期間・母数・欠測・根拠を連れて歩き、因果や推奨は出しません。
+- `serve-reports`: 専用環境向けの非公開レポート HTTP（Unix socket 既定・service credential・読むだけ）。**開発版**で、人の認証・TLS・一般提供は含みません。[限界](docs/非公開レポートHTTP_v1.md)。
+- X の本人公開指標の純粋な変換関数（API・投稿・台帳には未接続）。
+- 独立監査（P2 4・P3 7）とその直し: Unix socket 既定・要求全体の 10 秒 deadline・分離検査の走査を読取 dir に限定・期間比較の母集団から時刻不一致の返信を除外・git 無しでも import 可。
+
 ### v2.4.0 の変更
 
 - 利用者・管理者への停止／復旧メールと、元原稿の運用記録。設定・秘密は repo 外に保存します。導入時は [共通通知手順](docs/停止通知と運用記録.md) を実施します。
@@ -63,7 +70,7 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 - **英語の文書**: [README.en.md](README.en.md)・[docs/usage.en.md](docs/usage.en.md)・[llms.txt](llms.txt)。
 - **skill**: `skills/thth/SKILL.md`（wheel にも入る）。
 
-- **動くもの**（`thth --help` の全 36 サブコマンド）: `lint`・`preview`・`approve`・`account`・`revoke`・`posts`・`replies`・`measured`・`threads`・`after`・`topics`・`forms`・`queue`・`schedule`・`throw`・`run`・`systemd`・`board`・`collect`・`pull`・`auth`・`refresh`・`maintain`・`send`・`doctor`・`app`・`token`・`ask`・`mentions`・`profile`・`thread`・`where`・`who`・`retract`・`location`・`notifications`。
+- **動くもの**（`thth --help` の全 40 サブコマンド）: `lint`・`preview`・`approve`・`account`・`revoke`・`posts`・`replies`・`measured`・`threads`・`after`・`analytics-report`・`study-report`・`handoff-report`・`serve-reports`・`topics`・`forms`・`queue`・`schedule`・`throw`・`run`・`systemd`・`board`・`collect`・`pull`・`auth`・`refresh`・`maintain`・`send`・`doctor`・`app`・`token`・`ask`・`mentions`・`profile`・`thread`・`where`・`who`・`retract`・`location`・`notifications`。
 - **最初の本番投稿の記録**: 2026-09-09、@aoking に疎通確認を 1 本（`17916074118445631`）。
 - **未着手**: X・Facebook ページ・Instagram の各アダプタ。トピック検索の権限（tester には降りない）。泉のサーバ（v2-5）。
 - **権限の制約**: tester に降りる scope は 5 つ。削除はできない。
@@ -74,3 +81,12 @@ timer（systemd・`thth systemd` で生成）は10分ごとに実行し、投稿
 registry は「この PyPI の名前を名乗ってよいのは誰か」を、**配布物の README にこの 1 行があるか**で確かめる（設計 v2-4 §3・一次資料は quickstart・**L2**）。だから消さないこと——消すと登録（`mcp-publisher publish`）が通らなくなる。形（`server.json` と版の一致）は `tests/test_server_json.py` が見張る。
 
 mcp-name: io.github.aokings/thth
+
+## v3 基盤（2.5.0 から）
+
+`study-report` は明示した施策の宣言と本人の投稿観測を結ぶ読み取り専用レポートです。採用者の本人確認や因果効果は主張しません。[使い方と契約](docs/施策レポート_v1.md)。
+
+`analytics-report` はローカル台帳から期間・母数・欠測・根拠を揃えたスナップショットを返します。
+[形式と使い方](docs/分析レポート_v1.md)。
+
+`handoff-report` / MCP `operations_handoff` はローカル運用状態・通知未処理を鮮度の制約付きで返します。[形式と使い方](docs/運用引継ぎレポート_v1.md)。

{thth-2.4.0 → thth-2.5.0}/mcp/server.py

@@ -139,6 +139,34 @@ TOOLS = [
             "required": ["account", "topic"],
         },
     },
+    {
+        "name": "operations_handoff",
+        "description": "ローカル運用記録の状態・承認待ち・inflight・通知未処理を根拠と鮮度の制約付きで返す。同期・承認・再送はしない",
+        "inputSchema": {"type": "object", "properties": {
+            "account": {"type": "string"}, "project": {"type": "string"}}},
+    },
+    {
+        "name": "study_report",
+        "description": "ローカル施策JSONの未検証の採用宣言と本人の観測を結ぶ。proposedは集計せず、adoptedも因果効果や投稿承認を証明しない。読むだけ",
+        "inputSchema": {
+            "type": "object", "required": ["file"],
+            "properties": {"file": {"type": "string"}, "min_n": {"type": "integer"}},
+        },
+    },
+    {
+        "name": "analytics_report",
+        "description": "自分の活動のスナップショットを期間・母数・欠測・根拠つきで返す。ローカル台帳を読むだけ。compare_previous=trueで前期間比較。推奨は含まない",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "compare_previous": {"type": "boolean", "description": "直前の同じ日数との比較（既定false）"},
+                "account": {"type": "string"},
+                "project": {"type": "string"},
+                "window_days": {"type": "integer", "description": "直近何日（既定7）"},
+                "min_n": {"type": "integer", "description": "中央値の最小母数（既定5）"},
+            },
+        },
+    },
     {
         # **名前と説明文がそのまま売り文句**（設計「自分の泉」§2.2）。
         # 実装が 1 語でも足したら設計書でなく実装を戻す（§2 の頭書きそのまま）。
@@ -412,14 +440,14 @@ def validate_arguments(name: str, arguments) -> dict:
                         f"CLI の旗と区別できないので受け取りません")
         if key == "file":
             check_file_argument(name, value)
-    if name in ("after_you_posted", "where_to_appear", "who_is_this") \
+    if name in ("operations_handoff", "analytics_report", "after_you_posted", "where_to_appear", "who_is_this") \
             and not arguments.get("account") \
             and not arguments.get("project"):
         # **`account` か `project` のどちらか必須**（`required` は AND の意味しか
         # 持てないので、ここで OR を見る・T2-3 発注書・T3-3 も同じ形）。
         raise ToolInputError(
             f"{name}: account か project のどちらかが要ります")
-    if name == "after_you_posted" and arguments.get("account") \
+    if name in ("operations_handoff", "analytics_report", "after_you_posted") and arguments.get("account") \
             and arguments.get("project"):
         raise ToolInputError(
             f"{name}: account と project は同時に指定できません")
@@ -503,6 +531,36 @@ def call_tool(name: str, arguments: dict | None) -> dict:
         args.append("--json")
         proc = run_cli(args)
         text = proc.stdout
+    elif name == "operations_handoff":
+        args = ["handoff-report"]
+        if arguments.get("project"):
+            args += ["--project", arguments["project"]]
+        else:
+            args.append(arguments["account"])
+        args.append("--json")
+        proc = run_cli(args)
+        text = proc.stdout
+    elif name == "study_report":
+        args = ["study-report", arguments["file"]]
+        if arguments.get("min_n") is not None:
+            args += ["--min-n", str(arguments["min_n"])]
+        args.append("--json")
+        proc = run_cli(args)
+        text = proc.stdout
+    elif name == "analytics_report":
+        args = ["analytics-report"]
+        if arguments.get("project"):
+            args += ["--project", arguments["project"]]
+        else:
+            args.append(arguments["account"])
+        for key in ("window_days", "min_n"):
+            if arguments.get(key) is not None:
+                args += ["--" + key.replace("_", "-"), str(arguments[key])]
+        if arguments.get("compare_previous"):
+            args.append("--compare-previous")
+        args.append("--json")
+        proc = run_cli(args)
+        text = proc.stdout
     elif name == "after_you_posted":
         # **`before_you_post` と同じ型**（発注 T0-2）: CLI を `--json` で呼ぶだけ。
         args = ["after"]
@@ -579,7 +637,7 @@ def call_tool(name: str, arguments: dict | None) -> dict:
         return {"content": [{"type": "text", "text": f"unknown tool: {name}"}], "isError": True}
 
     if name.startswith("thth_topic_") or name in (
-            "before_you_post", "after_you_posted", "thread_read", "where_to_appear",
+            "before_you_post", "after_you_posted", "analytics_report", "operations_handoff", "study_report", "thread_read", "where_to_appear",
             "who_is_this"):
         # **新しい道具は exit 1 も isError**（設計 §7）。lint の exit 1（検査結果）
         # とは意味が違う——こちらは stale_context・不正な候補比較で、

{thth-2.4.0 → thth-2.5.0}/skills/thth/SKILL.md

@@ -127,6 +127,16 @@ MCP `after_you_posted`。**24h の刻みが無ければ `null`**（0 と混ぜ
 - `thth doctor <account>` が「いま投稿できる状態か」を最初から最後まで言う。
 - 使い方の全文: `docs/使い方_プロジェクトのセッション向け_2026-09-09.md`。
 
+## 運用と分析のレポート（v3系・2.5.0 から）
+
+2.4.0 以前には無い入口を含む。接続先のhelp/tools一覧にある場合だけ使う。
+
+- 再開時は `handoff-report` / MCP `operations_handoff`。ローカルの停止・要確認・通知記録を読む。`waiting`をtimer正常や投稿成功と解釈しない。
+- `analytics-report` / MCP `analytics_report` は期間・母数・欠測・根拠付きsnapshot。生成時刻とデータ更新時刻を混同しない。
+- 前期間比較は `--compare-previous` / `compare_previous: true`。投稿後24〜30時間未満の実観測で比較し、欠測をゼロにしない。
+- 施策メモの振り返りは `study-report` / `study_report`。採用宣言と観測を分け、提案を自動で採用済みにしない。投稿の承認には使えない。
+- 観測差を因果効果と断定しない。accountをまたいだ合算・順位を作らない。詳しい読み順は `docs/手順_LLM_分析と運用の引継ぎ.md`。
+
 ## 停止通知と運用状況（開発版 main）
 
 新規 account は利用者メール・管理者メール・TLS SMTP を `thth notifications config` で設定し、`status` → `test` を実行する。両宛先の受信箱で到達、account 専用 HEALTHCHECK_URL の missed-ping 通知を確認してから production/scheduled を有効にする。既存 account にも同じ設定を追加する。詳細は `docs/停止通知と運用記録.md`。

thth-2.5.0/tests/test_analytics_comparison.py

@@ -0,0 +1,213 @@
+"""Comparison contract: actual elapsed time, account isolation, incomplete samples."""
+import datetime
+import json
+from pathlib import Path
+
+import pytest
+
+from thth import analytics_report, after_cli, cli, jst
+from tests.test_after_cli import _insight_path, _write_ndjson, _seed_engagement, _load_server_module
+
+NOW = jst.parse("2026-09-18T12:00:00+09:00")
+
+
+def seed(account, post_id, posted, *, age=25, value=10, marks=None, extra=None):
+    posted = jst.parse(posted) if isinstance(posted, str) else posted
+    row = {"account": account["name"], "post_id": post_id, "posted_at": jst.iso(posted),
+           "collected_at": jst.iso(posted + datetime.timedelta(hours=age)),
+           "age_hours": 999, "marks": [24] if marks is None else marks,
+           "reply_to": None, "metrics": {"views": value, "likes": 0, "replies": 0}}
+    row.update(extra or {})
+    _write_ndjson(_insight_path(account, post_id), [row])
+    return row
+
+
+def report(account, **kwargs):
+    return analytics_report.answer(account["name"], now=NOW, compare_previous=True, **kwargs)
+
+
+def test_half_open_zero_delta_and_read_only(isolated_account_factory):
+    a = isolated_account_factory()
+    seed(a, "previous-start", NOW - datetime.timedelta(days=14), value=0)
+    seed(a, "current-start", NOW - datetime.timedelta(days=7), value=5)
+    seed(a, "end-excluded", NOW)
+    seed(a, "too-old", NOW - datetime.timedelta(days=14, seconds=1))
+    root = Path(a["repo_dir"])
+    before = {str(p): p.read_bytes() for p in root.rglob("*") if p.is_file()}
+    r = report(a, min_n=1)
+    p = r["by_account"][a["name"]]["posts"]
+    assert p["previous"]["n_total"] == p["current"]["n_total"] == 1
+    assert p["previous"]["metrics"]["views"]["median"] == 0
+    assert p["comparison"]["views"]["absolute_median_change"] == 5
+    assert p["previous"]["evidence"][0]["observation"]["actual_age_hours"] == 25
+    assert r["data_updated_at"] == jst.iso(NOW - datetime.timedelta(days=7) + datetime.timedelta(hours=25))
+    assert r["data_updated_at_scope"] == "selected_observations"
+    assert before == {str(p): p.read_bytes() for p in root.rglob("*") if p.is_file()}
+    assert not r["periods"]["previous"]["end_inclusive"]
+    markdown = analytics_report.render_markdown(r)
+    assert json.loads("\n".join(s[4:] for s in markdown.splitlines() if s.startswith("    "))) == r
+
+
+@pytest.mark.parametrize("age,marks,extra,reason", [
+    (23.99, [24], {}, "premature_observation"),
+    (30, [24], {}, "late_observation"),
+    (25, [1, 24], {}, "missing_or_collapsed_24h_mark"),
+    (25, [], {}, "missing_or_collapsed_24h_mark"),
+    (25, [24], {"collected_at": "bad"}, "invalid_collected_at"),
+    (25, [24], {"collected_at": "2026-09-18T13:00:00+09:00"}, "future_observation"),
+    (25, [24], {"collected_at": "2026-09-12T13:00:00"}, "invalid_collected_at"),
+])
+def test_rejected_observations(isolated_account_factory, age, marks, extra, reason):
+    a = isolated_account_factory()
+    seed(a, "p", NOW - datetime.timedelta(days=3), age=age, marks=marks, extra=extra)
+    p = report(a, min_n=1)["by_account"][a["name"]]["posts"]["current"]
+    assert (p["n_total"], p["n_eligible"], p["n_missing"], p["n_incomplete"]) == (1, 0, 1, 1)
+    assert p["metrics"]["views"]["median"] is None
+    assert p["evidence"][0]["rejected_observations"] == {reason: 1}
+    assert p["data_updated_at"] is None
+
+
+def test_immature_and_sparse_are_not_zero(isolated_account_factory):
+    a = isolated_account_factory()
+    seed(a, "new", NOW - datetime.timedelta(hours=1), age=0.5)
+    seed(a, "old", NOW - datetime.timedelta(days=8), value=0)
+    r = report(a, min_n=2)
+    p = r["by_account"][a["name"]]["posts"]
+    assert p["current"]["n_immature"] == 1
+    assert p["previous"]["metrics"]["views"]["n_eligible"] == 1
+    assert p["comparison"]["views"]["absolute_median_change"] is None
+    assert not p["comparison"]["views"]["comparable"]
+
+
+@pytest.mark.parametrize("value", [None, True, -1, float("nan"), float("inf"), "3", 10**1000])
+def test_invalid_metric_does_not_become_zero(isolated_account_factory, value):
+    a = isolated_account_factory()
+    seed(a, "p", NOW - datetime.timedelta(days=3), value=value)
+    p = report(a, min_n=1)["by_account"][a["name"]]["posts"]["current"]
+    assert p["n_eligible"] == 1  # time-eligible does not imply every metric exists
+    assert p["metrics"]["views"] == {"n_total": 1, "n_eligible": 0, "n_missing": 1, "median": None}
+    json.dumps(p, allow_nan=False)
+
+
+def test_earliest_actual_time_and_one_per_post(isolated_account_factory):
+    a = isolated_account_factory()
+    posted = NOW - datetime.timedelta(days=3)
+    later = seed(a, "p", posted, age=26, value=30)
+    earlier = dict(later, collected_at=(posted + datetime.timedelta(hours=24)).astimezone(datetime.timezone.utc).isoformat(), metrics={"likes": 3})
+    _write_ndjson(_insight_path(a, "p"), [later, earlier, earlier])
+    p = report(a, min_n=1)["by_account"][a["name"]]["posts"]["current"]
+    assert p["n_total"] == p["n_eligible"] == 1
+    assert p["metrics"]["views"]["n_eligible"] == 0  # never substitute later metric
+    assert p["metrics"]["likes"]["median"] == 3
+    assert p["evidence"][0]["observation"]["actual_age_hours"] == 24
+
+
+def test_ownership_reply_population_and_no_fallback(isolated_account_factory, monkeypatch):
+    a = isolated_account_factory()
+    posted = NOW - datetime.timedelta(days=3)
+    seed(a, "foreign", posted, extra={"account": "elsewhere"})
+    seed(a, "unknown", posted, extra={"account": None})
+    seed(a, "ambiguous-root", posted, extra={"source": "sent"})
+    seed(a, "reply", posted, extra={"metrics": {"views": 4}})
+    _seed_engagement(a, "reply", posted_at=jst.iso(posted))
+    _seed_engagement(a, "unmeasured", posted_at=jst.iso(posted))
+    monkeypatch.setattr(after_cli, "_replies_back_from_ledger", lambda *a: pytest.fail("no fallback"))
+    n = report(a, min_n=1)["by_account"][a["name"]]
+    assert n["posts"]["current"]["n_total"] == 0
+    assert n["engagements"]["current"]["n_total"] == 2
+    assert n["engagements"]["current"]["metrics"]["replies"]["n_eligible"] == 0
+    assert n["excluded_records"]["unknown_ownership"] == 1
+
+
+def test_project_isolation_and_broken_ledger(isolated_account_factory):
+    a = isolated_account_factory(name="one", project="p")
+    b = isolated_account_factory(name="two", project="p")
+    seed(a, "a", NOW - datetime.timedelta(days=3), value=0)
+    seed(b, "b", NOW - datetime.timedelta(days=3), value=10)
+    Path(_insight_path(a, "broken")).write_text("[broken")
+    r = analytics_report.answer(project="p", now=NOW, min_n=1, compare_previous=True)
+    assert r["by_account"]["one"]["posts"]["current"]["metrics"]["views"]["median"] == 0
+    assert r["by_account"]["two"]["posts"]["current"]["metrics"]["views"]["median"] == 10
+    assert r["by_account"]["one"]["incomplete_sources"]["measured_files"] == 1
+    assert "posts" not in r
+
+
+def test_cli_mcp_boolean_contract(isolated_account_factory, monkeypatch, capsys):
+    a = isolated_account_factory()
+    monkeypatch.setattr(analytics_report.jst, "now_jst", lambda: NOW)
+    assert cli.main(["analytics-report", a["name"], "--compare-previous", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out) == report(a)
+    server = _load_server_module()
+    result = server.call_tool("analytics_report", {"account": a["name"], "compare_previous": True})
+    assert not result["isError"]
+    assert json.loads(result["content"][0]["text"])["report_type"] == "period_comparison"
+    with pytest.raises(server.ToolInputError):
+        server.validate_arguments("analytics_report", {"account": a["name"], "compare_previous": "true"})
+    with pytest.raises(after_cli.AfterError):
+        report(a, window_days=10**100)
+    with pytest.raises(after_cli.AfterError):
+        analytics_report.answer(a["name"], compare_previous=1)
+
+
+@pytest.mark.parametrize("change", [{"reply_to": "parent"}, {"source": "sent"}, {"source": "unknown"}])
+def test_conflicting_row_root_classification_excluded(isolated_account_factory, change):
+    a = isolated_account_factory()
+    row = seed(a, "p", NOW - datetime.timedelta(days=3), age=1, marks=[1])
+    later = dict(row, collected_at=jst.iso(NOW - datetime.timedelta(days=2)), marks=[24], **change)
+    _write_ndjson(_insight_path(a, "p"), [row, later])
+    node = report(a, min_n=1)["by_account"][a["name"]]
+    assert node["posts"]["current"]["n_total"] == 0
+    assert node["excluded_records"]["conflicting_root_classification"] == 1
+
+
+def test_conflicting_row_posted_time_rejected(isolated_account_factory):
+    a = isolated_account_factory()
+    row = seed(a, "p", NOW - datetime.timedelta(days=3), age=1, marks=[1])
+    later = dict(row, collected_at=jst.iso(NOW - datetime.timedelta(days=2)), marks=[24],
+                 posted_at=jst.iso(NOW - datetime.timedelta(days=4)))
+    _write_ndjson(_insight_path(a, "p"), [row, later])
+    p = report(a, min_n=1)["by_account"][a["name"]]["posts"]["current"]
+    assert p["n_eligible"] == 0
+    assert p["evidence"][0]["rejected_observations"]["invalid_or_conflicting_posted_at"] == 1
+
+
+def test_duplicate_reply_and_conflicting_dates(isolated_account_factory):
+    a = isolated_account_factory()
+    posted = NOW - datetime.timedelta(days=3)
+    for _ in range(2):
+        _seed_engagement(a, "same", posted_at=jst.iso(posted))
+    _seed_engagement(a, "conflict", posted_at=jst.iso(posted))
+    _seed_engagement(a, "conflict", posted_at=jst.iso(posted - datetime.timedelta(days=1)))
+    node = report(a)["by_account"][a["name"]]
+    assert node["engagements"]["current"]["n_total"] == 1
+    assert node["excluded_records"]["invalid_or_conflicting_engagement_posted_at"] == 1
+
+
+def test_large_finite_metrics_stay_json_finite(isolated_account_factory):
+    a = isolated_account_factory()
+    seed(a, "p1", NOW - datetime.timedelta(days=3), value=1e308)
+    seed(a, "p2", NOW - datetime.timedelta(days=4), value=1e308)
+    r = report(a, min_n=2)
+    assert r["by_account"][a["name"]]["posts"]["current"]["metrics"]["views"]["median"] == 1e308
+    json.dumps(r, allow_nan=False)
+
+
+def test_malformed_loader_data_is_error_not_empty_population(isolated_account_factory):
+    a = isolated_account_factory()
+    seed(a, "p", NOW - datetime.timedelta(days=3), extra={"metrics": [1]})
+    with pytest.raises(after_cli.AfterError, match="台帳の形式"):
+        report(a)
+
+
+def test_conflicting_measured_reply_time_is_excluded_from_population(isolated_account_factory):
+    a = isolated_account_factory()
+    posted = NOW - datetime.timedelta(days=3)
+    seed(a, "reply-conflict", posted, extra={"reply_to": "parent"})
+    _seed_engagement(a, "reply-conflict", posted_at=jst.iso(posted - datetime.timedelta(days=1)))
+    node = report(a)["by_account"][a["name"]]
+    assert node["excluded_records"]["conflicting_measured_engagement_posted_at"] == 1
+    for kind in ("posts", "engagements"):
+        for period in ("previous", "current"):
+            population = node[kind][period]
+            assert population["n_total"] == population["n_missing"] == population["n_incomplete"] == 0
+            assert population["evidence"] == []

thth-2.5.0/tests/test_analytics_report.py

@@ -0,0 +1,115 @@
+"""Versioned snapshot: calculation parity, provenance and read-only boundaries."""
+import datetime
+import json
+from pathlib import Path
+
+import pytest
+
+from thth import after_cli, analytics_report, cli, jst
+from tests.test_after_cli import (_load_server_module, _seed_measured, _seed_engagement,
+                            _insight_path)
+
+NOW = jst.parse("2026-09-17T08:00:00+09:00")
+
+
+def test_boundaries_evidence_missing_and_no_writes(isolated_account_factory):
+    account = isolated_account_factory()
+    for name, time, marks in [
+        ("start", "2026-09-10T08:00:00+09:00", (24,)),
+        ("end", "2026-09-17T08:00:00+09:00", ()),
+        ("old", "2026-09-10T07:59:59+09:00", (24,)),
+        ("future", "2026-09-17T08:00:01+09:00", (24,)),
+    ]:
+        _seed_measured(account, name, posted_at=time, marks=marks)
+    _seed_engagement(account, "reply", posted_at="2026-09-12T08:00:00+09:00")
+    queue = Path(account["repo_dir"]) / "docs/sns/queue/protected.md"
+    queue.parent.mkdir(parents=True, exist_ok=True)
+    queue.write_text("---\napproved: true\n---\nPRIVATE BODY")
+    before = {p: p.read_bytes() for p in Path(account["repo_dir"]).rglob("*") if p.is_file()}
+    result = analytics_report.answer(account["name"], now=NOW)
+    after = {p: p.read_bytes() for p in Path(account["repo_dir"]).rglob("*") if p.is_file()}
+    assert before == after
+    node = result["by_account"][account["name"]]
+    original = after_cli.answer(account["name"], now=NOW, window_days=7)
+    for key in ("posts", "engagements", "comparable", "cannot_say"):
+        assert node[key] == original[key]
+    assert {p["post_id"] for p in node["posts"]["by_post"]} == {"start", "end"}
+    assert node["posts"]["views_24h"] == {"median": None, "n": 1}
+    end = next(p for p in node["posts"]["by_post"] if p["post_id"] == "end")
+    assert end["views_24h"] is None and end["covered"] is False
+    assert node["engagements"]["by_branch"][0]["post_id"] == "reply"
+    assert "one_thing_to_change" not in node
+    assert "updated" not in node["provenance"]
+    assert result["data_updated_at"] is None and result["data_updated_at_reason"]
+    assert result["period"]["start_inclusive"] and result["period"]["end_inclusive"]
+    assert result["period"]["start"] == "2026-09-10T08:00:00+09:00"
+    assert result["generated_at"] == "2026-09-17T08:00:00+09:00"
+    text = json.dumps(result)
+    assert "PRIVATE BODY" not in text
+    assert '"username"' not in text and '"text"' not in text
+    markdown = analytics_report.render_markdown(result)
+    recovered = "\n".join(line[4:] for line in markdown.splitlines() if line.startswith("    "))
+    assert json.loads(recovered) == result
+
+
+def test_project_separation_and_unknown_project(isolated_account_factory):
+    one = isolated_account_factory(name="one", project="same")
+    two = isolated_account_factory(name="two", project="same")
+    isolated_account_factory(name="outside", project="other")
+    _seed_measured(one, "P1", metrics={"views": 0})
+    _seed_measured(two, "P2", metrics={"views": 100})
+    result = analytics_report.answer(project="same", min_n=1, now=NOW)
+    assert set(result["by_account"]) == {"one", "two"}
+    assert result["by_account"]["one"]["posts"]["views_24h"]["median"] == 0
+    assert result["by_account"]["two"]["posts"]["views_24h"]["median"] == 100
+    assert "posts" not in result
+    with pytest.raises(after_cli.AfterError, match="account"):
+        analytics_report.answer(project="missing", now=NOW)
+
+
+def test_broken_ledger_is_not_silently_healthy(isolated_account_factory):
+    account = isolated_account_factory()
+    _seed_measured(account, "good")
+    path = Path(_insight_path(account, "bad"))
+    path.write_text("{broken json\n")
+    node = analytics_report.answer(account["name"], now=NOW)["by_account"][account["name"]]
+    assert any("読めない実測台帳" in line for line in node["cannot_say"])
+
+
+@pytest.mark.parametrize("kwargs", [{}, {"account_name": "a", "project": "p"},
+    {"account_name": ""}, {"project": " "}, {"account_name": "a", "window_days": True},
+    {"account_name": "a", "min_n": False}, {"account_name": "a", "window_days": 0},
+    {"account_name": "a", "min_n": 1.5}, {"account_name": "a", "window_days": 10**100},
+    {"account_name": "a", "now": datetime.datetime(2026, 9, 17)}])
+def test_invalid_input(kwargs):
+    with pytest.raises(after_cli.AfterError):
+        analytics_report.answer(**kwargs)
+
+
+def test_cli_and_mcp_same_payload(isolated_account_factory, monkeypatch, capsys):
+    account = isolated_account_factory()
+    _seed_measured(account, "root")
+    monkeypatch.setattr(analytics_report.jst, "now_jst", lambda: NOW)
+    assert cli.main(["analytics-report", account["name"], "--json"]) == 0
+    cli_result = json.loads(capsys.readouterr().out)
+    assert cli.main(["analytics-report", account["name"]]) == 0
+    assert capsys.readouterr().out == analytics_report.render_markdown(cli_result) + "\n"
+    server = _load_server_module()
+    result = server.call_tool("analytics_report", {"account": account["name"]})
+    assert not result["isError"]
+    payload = json.loads(result["content"][0]["text"])
+    expected = analytics_report.answer(account["name"], now=jst.parse(payload["generated_at"]))
+    assert payload == expected
+    assert cli.main(["analytics-report", "--project", "missing", "--json"]) == 2
+    assert capsys.readouterr().out == ""
+    assert server.call_tool("analytics_report", {"project": "missing"})["isError"]
+    assert server.call_tool("analytics_report", {"account": "missing"})["isError"]
+
+
+@pytest.mark.parametrize("args", [{}, {"account": "a", "project": "p"},
+    {"account": "a", "window_days": True}, {"account": "a", "min_n": False},
+    {"account": "a", "secret": "not-valid"}])
+def test_mcp_input_boundary(args):
+    server = _load_server_module()
+    with pytest.raises(server.ToolInputError):
+        server.validate_arguments("analytics_report", args)

{thth-2.4.0 → thth-2.5.0}/tests/test_board_running.py

@@ -49,6 +49,39 @@ def _hold(account_name, seconds, which="account"):
     return holder
 
 
+def _hold_until_released(account_name):
+    """Keep the lock until the parent closes stdin, regardless of CLI latency."""
+    code = """
+import sys
+from thth import accounts, lock
+held = lock.AccountLock(accounts.account_lock_path_for(sys.argv[1]))
+held.acquire()
+try:
+    print("locked", flush=True)
+    sys.stdin.read()
+finally:
+    held.release()
+"""
+    holder = subprocess.Popen(
+        [sys.executable, "-c", code, account_name],
+        stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        text=True, env=dict(os.environ),
+        cwd=os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    assert holder.stdout.readline().strip() == "locked"
+    return holder
+
+
+def _release(holder):
+    try:
+        # communicate closes stdin: that EOF is the explicit release event.
+        stdout, stderr = holder.communicate(timeout=5)
+    except subprocess.TimeoutExpired:
+        holder.kill()
+        holder.communicate(timeout=5)
+        raise
+    assert holder.returncode == 0, stdout + stderr
+
+
 def _stop(holder):
     holder.terminate()
     holder.wait(timeout=5)
@@ -146,7 +179,7 @@ def test_boardはロックを奪わない(isolated_account):
     name = isolated_account["name"]
     lock_path = accounts_mod.account_lock_path_for(name)
 
-    holder = _hold(name, 3)
+    holder = _hold_until_released(name)
     try:
         for _ in range(3):
             run_thth(["board"])
@@ -156,9 +189,8 @@ def test_boardはロックを奪わない(isolated_account):
         blocked = run_thth(["throw", name])
         assert blocked.returncode == 1, blocked.stdout + blocked.stderr
     finally:
-        holder.wait(timeout=15)
+        _release(holder)
 
-    time.sleep(0.2)
     # 放したあとは通る（board が握りっぱなしにしていない証拠）。
     assert lock_mod.AccountLock.holder_pid(lock_path) is None
     ok = run_thth(["throw", name])

{thth-2.4.0 → thth-2.5.0}/tests/test_cli_help.py

@@ -60,13 +60,13 @@ def _readme_ja_commands() -> list:
     text = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
     m = re.search(r"動くもの.*?: (.+?)。\n", text)
     assert m, "README.md に「動くもの」の行が見つかりません"
-    return re.findall(r"`([a-z_]+)`", m.group(1))
+    return re.findall(r"`([a-z_-]+)`", m.group(1))
 
 
 def _readme_en_commands() -> list:
     """README.en.md の Commands 節、`- \\`name\\` — ...` の形の行から名前を拾う。"""
     text = (REPO_ROOT / "README.en.md").read_text(encoding="utf-8")
-    return re.findall(r"^- `([a-z_]+)` — ", text, flags=re.MULTILINE)
+    return re.findall(r"^- `([a-z_-]+)` — ", text, flags=re.MULTILINE)
 
 
 def test_READMEの動くものの列挙はthth_helpの選択肢と一致する():