@geoly-ai/social-hub-cli 0.3.17 → 0.3.18

package/dist/register-feishu-identities.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=register-feishu-identities.test.d.ts.map

package/dist/register-feishu-identities.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-feishu-identities.test.d.ts","sourceRoot":"","sources":["../src/register-feishu-identities.test.ts"],"names":[],"mappings":""}

package/dist/register-feishu-identities.test.js

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { classifyHit, evaluateMassNotFound, } from "./register-feishu-identities.js";
+/**
+ * `not_found` 会**清空**已有的 open_id（离职语义）。如果 lark-cli 挂在另一个飞书
+ * 租户的授权上，全体查不到，一次 `--apply` 就能抹掉所有映射 —— 而这与「公司集体
+ * 离职」在数据上不可区分。这道判据是唯一挡在中间的东西，必须被锁住。
+ */
+describe("evaluateMassNotFound", () => {
+    const previously = new Set(["u1", "u2", "u3", "u4"]);
+    it("全部既有 resolved 变 not_found —— 停机", () => {
+        const result = evaluateMassNotFound(previously, [...previously].map((userId) => ({
+            userId,
+            resolveStatus: "not_found",
+        })));
+        expect(result).toEqual({ regressions: 4, massNotFound: true });
+    });
+    it("只掉一个人(真的有人离职)—— 放行", () => {
+        const result = evaluateMassNotFound(previously, [
+            { userId: "u1", resolveStatus: "not_found" },
+            { userId: "u2", resolveStatus: "resolved", openId: "ou_a" },
+            { userId: "u3", resolveStatus: "resolved", openId: "ou_b" },
+            { userId: "u4", resolveStatus: "resolved", openId: "ou_c" },
+        ]);
+        expect(result).toEqual({ regressions: 1, massNotFound: false });
+    });
+    /**
+     * `lookup_failed` 不清空 open_id，所以「整批查询失败」不该触发这道闸
+     * —— 否则真正危险的信号会被日常噪音淹没。
+     */
+    it("整批 lookup_failed 不算回归", () => {
+        const result = evaluateMassNotFound(previously, [...previously].map((userId) => ({
+            userId,
+            resolveStatus: "lookup_failed",
+            lastErrorCode: "token_expired",
+        })));
+        expect(result).toEqual({ regressions: 0, massNotFound: false });
+    });
+    it("此前一个都没映射上时不停机(首次同步)", () => {
+        const result = evaluateMassNotFound(new Set(), [
+            { userId: "u1", resolveStatus: "not_found" },
+            { userId: "u2", resolveStatus: "not_found" },
+        ]);
+        expect(result).toEqual({ regressions: 0, massNotFound: false });
+    });
+    it("恰好一半不触发,过半才触发(边界)", () => {
+        const half = evaluateMassNotFound(new Set(["u1", "u2"]), [
+            { userId: "u1", resolveStatus: "not_found" },
+            { userId: "u2", resolveStatus: "resolved", openId: "ou_a" },
+        ]);
+        expect(half.massNotFound).toBe(false);
+        const overHalf = evaluateMassNotFound(new Set(["u1", "u2", "u3"]), [
+            { userId: "u1", resolveStatus: "not_found" },
+            { userId: "u2", resolveStatus: "not_found" },
+            { userId: "u3", resolveStatus: "resolved", openId: "ou_a" },
+        ]);
+        expect(overHalf.massNotFound).toBe(true);
+    });
+    it("不在既有 resolved 名单里的 not_found 不算回归(本来就没映射)", () => {
+        const result = evaluateMassNotFound(new Set(["u1"]), [
+            { userId: "u9", resolveStatus: "not_found" },
+            { userId: "u8", resolveStatus: "not_found" },
+            { userId: "u1", resolveStatus: "resolved", openId: "ou_a" },
+        ]);
+        expect(result).toEqual({ regressions: 0, massNotFound: false });
+    });
+});
+/**
+ * 分类判据。只有「飞书压根没返回这个邮箱」才允许写 `not_found`
+ * —— 那一条会**清空**既有 open_id。其余"没拿到可用答案"必须是 `lookup_failed`。
+ */
+describe("classifyHit", () => {
+    it("飞书静默省略该邮箱 → not_found(真的不在通讯录)", () => {
+        expect(classifyHit("u1", undefined)).toEqual({
+            userId: "u1",
+            resolveStatus: "not_found",
+        });
+    });
+    it("命中了人但没有 open_id → lookup_failed,不清空既有映射", () => {
+        expect(classifyHit("u1", {})).toEqual({
+            userId: "u1",
+            resolveStatus: "lookup_failed",
+            lastErrorCode: "missing_open_id",
+        });
+    });
+    it("一个邮箱命中多个不同的人 → lookup_failed(歧义,不能挑一个)", () => {
+        expect(classifyHit("u1", { ambiguous: true })).toEqual({
+            userId: "u1",
+            resolveStatus: "lookup_failed",
+            lastErrorCode: "ambiguous_match",
+        });
+    });
+    it.each([
+        ["注入串", "ou_x></at><at user_id=all"],
+        ["缺前缀", "abc123"],
+        ["带引号", 'ou_abc"'],
+    ])("open_id 畸形(%s) → lookup_failed 而不是写进库", (_label, openId) => {
+        expect(classifyHit("u1", { openId })).toMatchObject({
+            resolveStatus: "lookup_failed",
+            lastErrorCode: "malformed_open_id",
+        });
+    });
+    it("union_id 畸形 → lookup_failed(不退化成只写 open_id)", () => {
+        expect(classifyHit("u1", { openId: "ou_ok1", unionId: "on_x></at>" })).toMatchObject({
+            resolveStatus: "lookup_failed",
+            lastErrorCode: "malformed_union_id",
+        });
+    });
+    it("合法命中 → resolved", () => {
+        expect(classifyHit("u1", { openId: "ou_ok1", unionId: "on_ok1" })).toEqual({
+            userId: "u1",
+            resolveStatus: "resolved",
+            openId: "ou_ok1",
+            unionId: "on_ok1",
+        });
+    });
+    it("没有 union_id 也能 resolved(该字段可缺)", () => {
+        expect(classifyHit("u1", { openId: "ou_ok1" })).toEqual({
+            userId: "u1",
+            resolveStatus: "resolved",
+            openId: "ou_ok1",
+        });
+    });
+});
+//# sourceMappingURL=register-feishu-identities.test.js.map

package/dist/register-feishu-identities.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-feishu-identities.test.js","sourceRoot":"","sources":["../src/register-feishu-identities.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "@geoly-ai/social-hub-authz": "0.0.14",
-    "@geoly-ai/social-hub-sdk": "0.0.54"
+    "@geoly-ai/social-hub-authz": "0.0.17",
+    "@geoly-ai/social-hub-sdk": "0.0.55"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "package": "social-ops-hub",
-  "cliVersion": "0.3.17",
+  "cliVersion": "0.3.18",
   "repository": "social-ops-hub",
   "publish": {
     "registry": "https://skill.sh",

package/skills/reddit-matrix.lock.json

@@ -28,7 +28,7 @@
       "contentSha256": "234d7fd1d8f2db68444674c20418c836c1b2488305b20399114dec89a0de32fc"
     },
     "reddit-voc-volume": {
-      "contentSha256": "45332556a0835a5c16386cb31550c04ea2447e2326a7a4ff15fd050f1ae91d55"
+      "contentSha256": "a5f21cc499688b245cfa3381ffdb88fa681cd5e93f3f1ef68d925b7ae220de2f"
     },
     "reddit-brand-risk-response": {
       "contentSha256": "dbba80345ebe68818a25e7604dfaa6951c6bf0e4d785d5013be7a06b22ec5b7c"

package/skills/reddit-voc-volume/SKILL.md

@@ -1,12 +1,7 @@
 ---
 name: reddit-voc-volume
 description: |
-  获取 Reddit VOC 声量、历史帖文、**历史评论正文/完整评论树**与公开 URL 证据：按关键词/品牌词搜索、指定 subreddit 扫描、批量链接汇总帖子量/评论量/score/子版分布，**按时间窗回溯 2005 年至今的历史帖子（正文全文，不截断）**，按帖子 URL/ID 从 Arctic Shift 拉取归档评论树或筛选/ID 批查评论正文，读取版规/wiki/subreddit 元数据，并通过 Social Hub 或自托管 Firecrawl 读取公开 About 页周访客/周贡献/周活跃用户兼容字段、Installed Apps、flair filters、通用 page_signals，以及**核验归档 score 与版规是否仍然现行**，输出结构化 JSON。
-  用户提到 Reddit VOC、品牌词/竞品讨论量、subreddit 声量、帖子评论量统计、**历史评论/评论正文/评论树/thread replies**、舆情采样、批量 Reddit 链接、about/rules/wiki、版规、**历史帖子/往年数据/时间窗回溯/某年某月的帖子/长期趋势**、置顶帖/pinned/sticky/megathread、公开 About 页周指标、Installed Apps、flair filters、页面公开链接信号，或需要**建 subreddit baseline 卡/统计正文长度分布**时必须用本 skill。
-  v2.12.28 起 reddit `.json` 直采已全部移除：搜索/帖子/about/版规/wiki 一律走 Arctic Shift 归档 API（`history` 模式 + Emergency Acquisition），正文不截断；归档 `score` 带 `score_status`，只有 `Backfilled`/`VerifiedLive` 可用于声量，`--verify-scores` / `--verify-rules` 用 Firecrawl 渲染页核验实时值。**置顶是 live 语义，本地已无采集途径，只能走 Social Hub**，取不到标 NotVisible，不得用归档 stickied 代替。
-  **历史数据类意图直连 Arctic，不走 Hub-First**：历史帖子 / 往年数据 / 时间窗回溯 / 某年某月 / 长期趋势 / 建 subreddit baseline 卡需历史样本，一律直接路由到 `history` 模式(Arctic Shift 深度归档，权威源，正文不截断)，**不经 Hub-First 四级链路**——Hub 只有近实时缓存、不持有深度归档，历史查 Hub 是浪费且拿不到。仅「当下声量」类(`keyword` / `subreddit` 及证据类模式)才走 Hub-First。
-  Hub-First 链路(仅当下声量/证据类，不含 history/comments)：`keyword` / `subreddit` 及证据类模式先查 Social Hub(voc-query/evidence-status)，缺口由 Hub 派发(dispatch-on-gap/evidence-fetch)并轮询 runs(partial 定向重派一次)；仅 Hub failed/timeout/unreachable 才进入本地 Emergency Acquisition，本地成功结果自动回灌 Hub(hot-posts-create/evidence-import)，coverage 满足但读不到 items 时输出 itemsUnavailable 而非假成功。不用于全站爬取、绕过登录墙或读取 mod 后台。
-  v2.12.31 新增 `comments`：默认 `/api/comments/tree` 拉取最多 25,000 条归档评论并保留层级；也支持 `/api/comments/search` 筛选及 `/api/comments/ids` 最多 500 ID 批查。该模式固定直连 Arctic，不走 Hub-First；归档通常滞后约 2 小时且无 uptime 保证，评论 `score` 不是实时值。
+  获取 Reddit VOC 声量、历史帖子/评论正文与可还原评论树，以及公开 URL、about、rules、wiki 和页面证据，输出结构化 JSON。用户询问关键词/品牌/竞品讨论量、subreddit 声量、帖子评论量、历史帖子/往年/绝对时间窗/长期趋势、历史评论/评论正文/评论树/thread replies、批量 Reddit 链接、版规/wiki/about、置顶帖、flair filters、Installed Apps、周访客/贡献/活跃用户，或建立 subreddit baseline 时使用。历史帖子与 comments 固定直连 Arctic Shift，不走 Hub-First；comments 默认 tree（最多 25,000，保留 parent_id 与树坐标），也支持 search 的 body/author/after/before/parent_id 筛选和 IDs 批查。Arctic 通常滞后约 2 小时、无 uptime 保证，归档评论 score 非实时。当下 keyword/subreddit/证据模式走 Hub-First，缺口才本地 Emergency Acquisition；置顶为 live 语义，只走 Social Hub，取不到标 NotVisible。
 ---
 
 # Reddit VOC 声量
@@ -186,7 +181,7 @@ python3 "$VOC" links \
 若 Arctic 因上限或宽深度折叠返回 `kind=more`，这些节点不会伪装成评论；它们原样进入
 `collapsed[]`（含 `parent_id` / `children` / `count` / 树坐标），同时
 `tree_complete=false`。请求失败或响应不是合法的 Arctic `data[]` 评论树时同样输出
-`ok=false`、`tree_complete=false`；只有请求成功、结构合法且 `collapsed_count=0`
+`ok=false`、`tree_complete=false`；只有请求成功、结构合法、`collapsed_count=0` 且未触达请求 limit
 才能把当次结果视为完整树。
 
 - `--source search` 调 `/api/comments/search`，上限 100；支持 `--body`（Arctic FTS）、

package/skills/reddit-voc-volume/matrix-contract.md

@@ -28,9 +28,10 @@ Search/subreddit/post samples are preference signals only. They must not be used
 `comments` bodies are historical VOC / preference evidence only. Consumers may reconstruct
 the thread from `parent_id`, `depth`, `sibling_index`, `tree_order`, and `tree_path`. They must
 require `tree_complete=true` before describing a result as the complete thread; otherwise
-`collapsed[]` records the unexpanded IDs. Fetch failures and malformed tree payloads explicitly
-set `tree_complete=false` even when `collapsed[]` is empty. `score_status=ArchivedSnapshot` and
-`score_realtime=false` are binding: archived comment scores cannot support current-hot claims.
+`collapsed[]` records the unexpanded IDs. Fetch failures, malformed tree payloads, and an exact
+tree limit hit explicitly set `tree_complete=false` even when `collapsed[]` is empty.
+`score_status=ArchivedSnapshot` and `score_realtime=false` are binding: archived comment scores
+cannot support current-hot claims.
 
 `links` output for `subreddit_rules`, `wiki_page`, and `subreddit_about` can be used
 as public source evidence for `reddit-subreddit-compliance`. VOC still does not

package/skills/reddit-voc-volume/references/arctic-shift.md

@@ -53,7 +53,8 @@ Skill 入口统一为 `comments`。默认 tree；扁平 item 保留完整 `body`
 `tree_path` / `child_ids`。`kind=more` 单独进入 `collapsed[]`；只要存在折叠节点，
 `tree_complete=false`，不得声称已经拿到完整评论树。请求失败或响应不是合法
 `data[]` 树时也必须 `ok=false`、`tree_complete=false`，不能因为 `collapsed=[]`
-误报完整。
+误报完整。若返回的实际评论数恰好触达本次 `limit`，即使没有 `kind=more` 也无法
+排除上游截断；此时 `tree_limit_reached=true`、`tree_complete=false`，继续保持保守语义。
 
 `parent_id` 语义按端点区分：tree 只接受裸/t1_ 评论 ID（取子树）；search 的
 `--parent-id top|root` 会显式发送空 `parent_id=` 以筛顶层评论，不能伪造成 t3_ post ID。

package/skills/reddit-voc-volume/scripts/reddit_voc_volume.py

@@ -145,7 +145,7 @@ SOCIAL_HUB_REQUIRED_SKILLS = ("social-hub-cli", "social-hub-shared")
 HUB_DEFAULT_POLL_TIMEOUT_SEC = 600.0
 HUB_POLL_BACKOFF_SEC = (5.0, 10.0, 20.0, 30.0)
 HUB_INTELLIGENCE_TIMEOUT_SEC = 30.0
-COLLECTOR_VERSION = "2.12.31"
+COLLECTOR_VERSION = "2.12.32"
 ACQUISITION_POLICIES = ("hub-first", "hub-only", "self-first")
 DEFAULT_FLAIR_FILTER_PAGES = ("", "hot", "new", "top")
 
@@ -3285,7 +3285,7 @@ def arctic_search_posts(
     return [arctic_post_item(r) for r in rows if isinstance(r, dict)]
 
 
-_ARCTIC_BASE36_ID_RE = re.compile(r"^[0-9a-z]+$", re.I)
+_ARCTIC_BASE36_ID_RE = re.compile(r"^[0-9a-z]{1,32}$", re.I)
 
 
 def normalize_reddit_post_id(target: str) -> str:
@@ -3300,14 +3300,17 @@ def normalize_reddit_post_id(target: str) -> str:
         parsed = urllib.parse.urlparse(raw)
         host = (parsed.hostname or "").lower().rstrip(".")
         if host == "redd.it" or host.endswith(".redd.it"):
-            candidate = parsed.path.strip("/").split("/", 1)[0]
+            path_parts = parsed.path.strip("/").split("/")
+            candidate = path_parts[0] if len(path_parts) == 1 else ""
         elif host == "reddit.com" or host.endswith(".reddit.com"):
             match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", parsed.path, re.I)
             candidate = match.group(1) if match else ""
         else:
             raise ValueError(f"unsupported post URL host: {host or '<missing>'}")
-    elif "/comments/" in raw:
+    elif re.match(r"^/?(?:r/[^/]+/)?comments/", raw, re.I):
         match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", raw, re.I)
+        if match is None:
+            match = re.search(r"^comments/([0-9a-z]+)(?:/|$)", raw, re.I)
         candidate = match.group(1) if match else ""
     else:
         candidate = raw[3:] if raw.lower().startswith("t3_") else raw
@@ -3361,6 +3364,18 @@ def normalize_comment_parent_id(parent_id: str | None, *, allow_top_level: bool
     return f"t1_{normalize_reddit_comment_id(raw)}"
 
 
+def _arctic_comment_rows(payload: Any, *, endpoint: str) -> list[dict[str, Any]]:
+    """Require the documented ``{"data": object[]}`` comment response shape."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("data"), list):
+        raise ArcticError(f"arctic_comments_{endpoint}_malformed_payload: expected data[]")
+    rows = payload["data"]
+    if any(not isinstance(row, dict) for row in rows):
+        raise ArcticError(
+            f"arctic_comments_{endpoint}_malformed_payload: data must contain object rows"
+        )
+    return rows
+
+
 def arctic_comment_item(
     row: dict[str, Any],
     *,
@@ -3372,10 +3387,15 @@ def arctic_comment_item(
 ) -> dict[str, Any]:
     """Map an Arctic comment row without truncating its archived body."""
     body = row.get("body")
+    if body is not None and not isinstance(body, str):
+        raise ArcticError("arctic_comments_malformed_comment: body must be a string or null")
     body_text = body if isinstance(body, str) else ("" if body is None else str(body))
     body_status = classify_body(body_text)
     measurable = body_status not in ("Removed", "Deleted")
-    comment_id = str(row.get("id") or "").removeprefix("t1_").lower()
+    try:
+        comment_id = normalize_reddit_comment_id(str(row.get("id") or ""))
+    except ValueError as exc:
+        raise ArcticError(f"arctic_comments_malformed_comment: {exc}") from exc
     permalink = str(row.get("permalink") or "")
     if permalink.startswith("/"):
         permalink = f"https://www.reddit.com{permalink}"
@@ -3434,63 +3454,93 @@ def flatten_arctic_comment_tree(payload: Any) -> tuple[list[dict[str, Any]], lis
     roots = payload.get("data")
     if any(not isinstance(node, dict) for node in roots):
         raise ArcticError("arctic_comments_tree_malformed_payload: data must contain object nodes")
-    nodes = roots
     items: list[dict[str, Any]] = []
     collapsed: list[dict[str, Any]] = []
-    order = 0
-
-    def walk(children: list[dict[str, Any]], *, depth: int, path: list[int], parent_id: str | None) -> None:
-        nonlocal order
-        for sibling_index, node in enumerate(children):
-            kind = str(node.get("kind") or "")
-            data = node.get("data")
-            if not isinstance(data, dict):
-                raise ArcticError("arctic_comments_tree_malformed_payload: node.data must be an object")
-            node_path = [*path, sibling_index]
-            node_order = order
-            order += 1
-            if kind == "more":
-                child_ids = [
-                    normalize_reddit_comment_id(str(value))
-                    for value in (data.get("children") or [])
-                    if str(value or "").strip()
-                ]
-                collapsed.append(
-                    {
-                        "kind": "more",
-                        "id": data.get("id"),
-                        "parent_id": data.get("parent_id") or parent_id,
-                        "count": data.get("count"),
-                        "children": child_ids,
-                        "depth": depth,
-                        "tree_order": node_order,
-                        "sibling_index": sibling_index,
-                        "tree_path": node_path,
-                    }
+    seen_comment_ids: set[str] = set()
+    # Iterative preorder traversal: a valid 25,000-comment chain must not hit
+    # Python's recursion limit merely because the archived thread is deep.
+    stack: list[tuple[dict[str, Any], int, list[int], str | None, int]] = [
+        (node, 0, [sibling_index], None, sibling_index)
+        for sibling_index, node in reversed(list(enumerate(roots)))
+    ]
+
+    while stack:
+        node, depth, node_path, parent_id, sibling_index = stack.pop()
+        kind = str(node.get("kind") or "")
+        data = node.get("data")
+        if not isinstance(data, dict):
+            raise ArcticError("arctic_comments_tree_malformed_payload: node.data must be an object")
+        node_order = len(items) + len(collapsed)
+        if kind == "more":
+            raw_child_ids = data.get("children")
+            if raw_child_ids is None:
+                raw_child_ids = []
+            if not isinstance(raw_child_ids, list):
+                raise ArcticError(
+                    "arctic_comments_tree_malformed_payload: more.children must be an array"
                 )
-                continue
-            if kind != "t1":
-                raise ArcticError(f"arctic_comments_tree_malformed_payload: unexpected kind={kind or '<empty>'}")
-
-            replies = _arctic_tree_children(data.get("replies"))
-            item = arctic_comment_item(
-                data,
-                depth=depth,
-                tree_order=node_order,
-                sibling_index=sibling_index,
-                tree_path=node_path,
-                tree_parent_id=parent_id,
+            try:
+                child_ids = [normalize_reddit_comment_id(str(value)) for value in raw_child_ids]
+            except ValueError as exc:
+                raise ArcticError(
+                    f"arctic_comments_tree_malformed_payload: invalid more child ID: {exc}"
+                ) from exc
+            collapsed.append(
+                {
+                    "kind": "more",
+                    "id": data.get("id"),
+                    "parent_id": data.get("parent_id") or parent_id,
+                    "count": data.get("count"),
+                    "children": child_ids,
+                    "depth": depth,
+                    "tree_order": node_order,
+                    "sibling_index": sibling_index,
+                    "tree_path": node_path,
+                }
+            )
+            continue
+        if kind != "t1":
+            raise ArcticError(
+                f"arctic_comments_tree_malformed_payload: unexpected kind={kind or '<empty>'}"
+            )
+
+        replies = _arctic_tree_children(data.get("replies"))
+        item = arctic_comment_item(
+            data,
+            depth=depth,
+            tree_order=node_order,
+            sibling_index=sibling_index,
+            tree_path=node_path,
+            tree_parent_id=parent_id,
+        )
+        if item["id"] in seen_comment_ids:
+            raise ArcticError(
+                f"arctic_comments_tree_malformed_payload: duplicate comment ID {item['id']}"
             )
+        seen_comment_ids.add(item["id"])
+        try:
             item["child_ids"] = [
-                str(child.get("data", {}).get("id") or "").removeprefix("t1_").lower()
+                normalize_reddit_comment_id(str(child["data"].get("id") or ""))
                 for child in replies
                 if child.get("kind") == "t1" and isinstance(child.get("data"), dict)
             ]
-            items.append(item)
-            current_parent = str(data.get("name") or (f"t1_{item['id']}" if item.get("id") else "")) or None
-            walk(replies, depth=depth + 1, path=node_path, parent_id=current_parent)
+        except ValueError as exc:
+            raise ArcticError(
+                f"arctic_comments_tree_malformed_payload: invalid child comment ID: {exc}"
+            ) from exc
+        items.append(item)
+        current_parent = str(data.get("name") or f"t1_{item['id']}")
+        for child_index, child in reversed(list(enumerate(replies))):
+            stack.append(
+                (
+                    child,
+                    depth + 1,
+                    [*node_path, child_index],
+                    current_parent,
+                    child_index,
+                )
+            )
 
-    walk(nodes, depth=0, path=[], parent_id=None)
     return items, collapsed
 
 
@@ -3516,7 +3566,13 @@ def arctic_comments_tree(
         user_agent=user_agent,
         tracker=tracker,
     )
-    return flatten_arctic_comment_tree(payload)
+    items, collapsed = flatten_arctic_comment_tree(payload)
+    expected_link_id = f"t3_{post_id}"
+    if any(str(item.get("link_id") or "").lower() != expected_link_id for item in items):
+        raise ArcticError(
+            "arctic_comments_tree_malformed_payload: comment link_id does not match requested post"
+        )
+    return items, collapsed
 
 
 def arctic_search_comments(
@@ -3548,14 +3604,17 @@ def arctic_search_comments(
         tracker=tracker,
         keep_empty_params={"parent_id"} if parent_id == "" else None,
     )
-    rows = payload.get("data")
-    if not isinstance(rows, list):
-        return []
-    return [
-        arctic_comment_item(row, tree_order=index)
-        for index, row in enumerate(rows)
-        if isinstance(row, dict)
-    ]
+    rows = _arctic_comment_rows(payload, endpoint="search")
+    items = [arctic_comment_item(row, tree_order=index) for index, row in enumerate(rows)]
+    expected_link_id = f"t3_{post_id}"
+    if any(str(item.get("link_id") or "").lower() != expected_link_id for item in items):
+        raise ArcticError(
+            "arctic_comments_search_malformed_payload: comment link_id does not match requested post"
+        )
+    item_ids = [str(item["id"]) for item in items]
+    if len(item_ids) != len(set(item_ids)):
+        raise ArcticError("arctic_comments_search_malformed_payload: duplicate comment IDs")
+    return items
 
 
 def arctic_comments_by_ids(
@@ -3570,12 +3629,24 @@ def arctic_comments_by_ids(
         user_agent=user_agent,
         tracker=tracker,
     )
-    rows = payload.get("data")
-    by_id = {
-        str(row.get("id") or "").removeprefix("t1_").lower(): row
-        for row in (rows if isinstance(rows, list) else [])
-        if isinstance(row, dict)
-    }
+    rows = _arctic_comment_rows(payload, endpoint="ids")
+    by_id: dict[str, dict[str, Any]] = {}
+    for row in rows:
+        try:
+            item_id = normalize_reddit_comment_id(str(row.get("id") or ""))
+        except ValueError as exc:
+            raise ArcticError(f"arctic_comments_ids_malformed_payload: {exc}") from exc
+        if item_id in by_id:
+            raise ArcticError(
+                f"arctic_comments_ids_malformed_payload: duplicate comment ID {item_id}"
+            )
+        by_id[item_id] = row
+    unexpected_ids = sorted(set(by_id).difference(comment_ids))
+    if unexpected_ids:
+        raise ArcticError(
+            "arctic_comments_ids_malformed_payload: unexpected comment IDs "
+            + ",".join(unexpected_ids[:10])
+        )
     items = [
         arctic_comment_item(by_id[comment_id], tree_order=index)
         for index, comment_id in enumerate(comment_ids)
@@ -4991,6 +5062,7 @@ def main() -> int:
         missing_ids: list[str] = []
         items: list[dict[str, Any]] = []
         tree_fetch_succeeded = False
+        tree_limit_reached = False
         try:
             if retrieval_mode == "ids":
                 items, missing_ids = arctic_comments_by_ids(
@@ -5022,6 +5094,9 @@ def main() -> int:
                     tracker=tracker,
                 )
                 tree_fetch_succeeded = True
+                # At the exact cap, absence of `kind=more` is not proof that the
+                # upstream did not truncate. Completeness must remain fail-closed.
+                tree_limit_reached = len(items) >= limit
         except ArcticError as exc:
             errors.append(f"arctic_comments_failed:{exc}"[:300])
         if missing_ids:
@@ -5038,6 +5113,11 @@ def main() -> int:
                 f"评论树含 {len(collapsed)} 个 kind=more 折叠节点；"
                 "tree_complete=false，collapsed[].children 保留尚未展开的评论 ID。"
             )
+        if tree_limit_reached:
+            notes.append(
+                f"评论数已触达本次 tree limit={limit}；即使没有 kind=more，也不能证明树完整，"
+                "tree_complete=false。"
+            )
         fetched_at = utc_now_iso()
         canonical_source = f"https://www.reddit.com/comments/{post_id}/" if post_id else None
         fingerprint = hashlib.sha256(
@@ -5081,7 +5161,12 @@ def main() -> int:
                 "sort": args.sort or ("asc" if retrieval_mode == "search" else None),
             },
             "count": len(items),
-            "tree_complete": tree_fetch_succeeded and not collapsed if retrieval_mode == "tree" else None,
+            "tree_complete": (
+                tree_fetch_succeeded and not collapsed and not tree_limit_reached
+                if retrieval_mode == "tree"
+                else None
+            ),
+            "tree_limit_reached": tree_limit_reached if retrieval_mode == "tree" else None,
             "collapsed_count": len(collapsed),
             "collapsed": collapsed,
             "body_stats": {
@@ -5099,6 +5184,9 @@ def main() -> int:
                 "requested_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
                 "effective_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
                 "http_requests": tracker.count,
+                "truncated": bool(collapsed or tree_limit_reached)
+                if retrieval_mode == "tree"
+                else False,
                 "rate_limited": tracker.rate_limited,
             },
             "fetched_at": fetched_at,