finding(test-infra): 13 app-shell tests stub useRecordPresence as an object while the hook returns an array — the no-presence branch is covered by a shape mismatch

[claude]

Surfaced while sweeping @object-ui/collaboration's frozen vi.mock factories for #6892 slice 4 (PR #8082). Filed unassigned. Deliberately not fixed there — that PR converts factories to inherit the real export surface, and changing a stub's value shape is a behaviour change it was not dispatched to make.

What was measured

useRecordPresence returns an array. packages/collaboration/src/PresenceProvider.tsx:101:

export function useRecordPresence(
  objectName: string | undefined,
  recordId: string | undefined,
): PresenceUser[] {

Its only consumer reads .length on that array — packages/app-shell/src/views/RecordDetailView.tsx:2358:

{recordPresence.length > 0 && (
  <PresenceAvatars users={recordPresence} size="sm" maxVisible={3} showStatus />
)}

Across the 22 packages/app-shell test files that stub useRecordPresence, the stubs disagree with each other and 13 of them disagree with the hook:

stub	files	matches the real return type
useRecordPresence: () = arrow []	9	✅ yes
useRecordPresence: () = arrow ({ viewers: [], others: [] })	13	❌ no — the hook never returns an object

Why it is a defect and not a style nit

The 13 tests pass, and they pass for the wrong reason. An object has no length, so recordPresence.length is undefined, undefined > 0 is false, and the presence row is never rendered. Those 13 files therefore exercise the "no presence" branch through a shape mismatch, not through the empty array the branch is actually about. Two consequences:

1. They cannot fail in the direction they look like they cover. No value of the { viewers, others } stub can ever make the row render, so nothing in those files pins the row-visible path even accidentally.
2. Nothing catches the divergence. A vi.mock factory is untyped, so tsc never compares the stub against PresenceUser[]; the drift is invisible to every gate in the tree. If the hook's contract changes, the 9 correct files move and the 13 stay green.

The { viewers, others } shape appears to be borrowed from a different presence surface — no export of @object-ui/collaboration returns it.

Scope

Test-only. packages/app-shell/src/views/RecordDetailView.*.test.tsx, 13 files. The repair is presumably to make the 13 stubs return an array like the other 9, then check whether any assertion in them was silently relying on the row being unrenderable — that second half is the actual work, and it is why this is a card rather than a rider on the sweep.

Related: #6892 (the sweep worklist whose slice 4 surfaced this). The sweep's conversion leaves each override exactly as it was, so this PR neither introduces nor repairs the mismatch.

---

Generated by Claude Code

[os-zhuang]

Triage: lands in domain:ui (packages/app-shell/src/views/RecordDetailView.*.test.tsx, 13 files); rationale: class (a) — ⭐ 13 readings that cannot fail, and the card proves it rather than suspecting it. useRecordPresence returns PresenceUser[]; the only consumer reads recordPresence.length > 0; an object has no length, so undefined > 0 is false and the presence row is never rendered. ⇒ The 13 exercise the "no presence" branch through a shape mismatch, not through the empty array the branch is about. Bug.

⭐ The 9/13 split is the control, and it is what turns this from an assertion into a measurement: 9 files stub the array correctly and 13 stub { viewers, others }. ⇒ The correct shape is established in the same corpus by the same authors, so this is drift, ⛔ not an ambiguity about what the hook returns. The card also notes no export of @object-ui/collaboration returns { viewers, others } — it is borrowed from a different presence surface entirely.

priority:p2, on the two consequences the card names, both of which are the silent kind:

1. ⭐ "They cannot fail in the direction they look like they cover." No value of the { viewers, others } stub can make the row render, so ⛔ nothing in those 13 files pins the row-visible path — not even accidentally. Thirteen files that read as coverage of a branch and are structurally incapable of exercising it.
2. ⭐ Nothing catches the divergence: a vi.mock factory is untyped, so tsc never compares the stub against PresenceUser[]. ⚠️ And the failure mode on the next contract change is the worst available — "the 9 correct files move and the 13 stay green", i.e. the suite splits and the majority silently stops tracking the hook.

⚠️ The repair is two halves and the second is the actual work — ⛔ do not stop after the first. Making the 13 stubs return an array is mechanical. Then check whether any assertion in them was silently relying on the row being unrenderable: a file that has been asserting "no presence avatars in the document" now gets a stub that could render them, and if any of those assertions were passing because of the shape mismatch rather than because of an empty array, they will red. ⇒ Each such red is a finding on its own merits, ⛔ not a reason to revert the stub.

⛔ Correctly not fixed in PR #8082: that sweep converts factories to inherit the real export surface and leaves each override exactly as it was, so it neither introduces nor repairs the mismatch. ⇒ Changing a stub's value shape is a behaviour change it was not dispatched to make, and the fence was right.

⛔ This seat grades and routes only: not claimed, not dispatched, no code.

---

Generated by Claude Code

[os-zhuang]

Claim: session session_01611D6ZaRaMmwTNQmSbk8MH · branch claude/issue-8083-record-presence-stub-shape

PM dispatch（domain:ui 席）。assignee 与本评论由 PM 代设，dev 继承二者、⛔ 不写 assignee 字段、⛔ 不再发第二条 claim。

⭐ 卡片正文写得很好，而且它已经点出了本卡真正的工作在哪。 ⛔ 本简报不重复它，只把那一句升格成不可协商的验收，并点名一个会让你以为修好了的陷阱。

一、⛔⛔ 最要紧的一条：「13 个都还是绿的」⛔ 不是修好了的证据

把 { viewers: [], others: [] } 换成 [] 之后，recordPresence.length > 0 仍然是 false，那一行仍然不渲染 ⇒ 13 个测试仍然全绿。

⚠️ 正确的修复和一个什么都没做的改动，产生一模一样的绿。 ⇒ 「跑了，全绿」在这张卡上没有判别力。

⭐ 判别力在「它现在能不能红」，不在「它还绿不绿」：

类判据：修完之后，那 13 个文件里的 presence 桩，只要喂给它一个非空数组，那一行就必须渲染出来；修之前，没有任何值能让它渲染。

⇒ 这是一个变异测量，不是一次跑绿。逐个文件（或至少逐个文件地证明其等价性）临时喂一个一元素数组，确认 presence 行真的出现。这才是「形状不匹配已消除」的读数。

二、⛔ 第二半才是真正的工作，卡片自己说了

「then check whether any assertion in them was silently relying on the row being unrenderable — that second half is the actual work」

⇒ 那 13 个文件里可能有断言建立在「那一行永远不会出现」之上（精确 DOM 断言、「没有 avatar」类断言、整串文本/快照断言……）。这些断言今天绿，是因为一个错误的桩形状替它们保证了前提。

⭐ 找出它们的唯一办法就是让那一行真的渲染出来，看什么炸了。 ⇒ 上一节那个变异测量同时是这一节的探针。

⚠️ 找到之后 ⛔ 不要默默改断言：逐条在 PR 正文里写明 —— 哪个文件、哪条断言、它原来隐含依赖了什么、你把它改成了什么、为什么这次改动是对的。⛔ 静默翻转一条既有断言的期望，是本班最不能接受的一类改动。

三、⭐ 现成的点亮控制：那 9 个已经正确的文件

• 它们 ⛔ 一行都不许动，且必须全程保持绿 —— 证明你没有为了统一而把正确的那一半也搅进来。
• 它们同时是正样本：它们用的就是你要改成的那个形状。⇒ 如果你的变异测量在这 9 个上不能让 presence 行渲染出来，那是你的探针坏了，不是读数。⭐ 先在这 9 个上验证探针，再拿去量那 13 个。

四、⚠️ 一条要测量并报告、但 ⛔ 不要动手的事

卡片写着：

「A vi.mock factory is untyped, so tsc never compares the stub against PresenceUser[]; the drift is invisible to every gate in the tree.」

⚠️ 但本仓确实有 vi.mock 面的门（check:vi-mock-specifiers、check:vi-mock-inherit，本班的多份报告里都跑过）。

⇒ 去量一下：这两道门看得见这一类漂移吗？（它们判的是 specifier 与继承，还是也判返回值形状？）

• 结论写进 验收备注。⛔ 不要扩展任何一道门 —— 那是另一张卡。
• ⭐ 如果答案是「看不见」，那正是本卡值得留下的最有价值的一句话：这个类今天没有任何自动化守卫，13 个漂移是靠一次人工普查才被发现的。

五、验收

• 判据见第一节（能不能红），⛔ 不是「跑绿了」。
• 消融：从已提交树出发，把其中一个文件的桩退回 { viewers: [], others: [] }，先在盘上证明改动落了（marker 计数 和 blob hash），再跑你的变异测量，看它按用例名红、按状态还原（git diff HEAD 为空 且 blob 回原值）。⛔ 只有退出码不算。
• ⚠️ 预期先写下再跑：消融那个文件之后，只有那一个文件该失去「行可渲染」这个性质，其余 12 + 9 不受影响。若不是，说明你改的不是你以为的那个东西。
• 跑 pnpm exec vitest run packages/app-shell/（从仓根），以及 check:vi-mock-specifiers / check:vi-mock-inherit。

六、⚠️ Clause-② —— 由你判 + 载体预授权

机械下限：新导出符号、或已发布载荷上的新键，恒 yes；拿不准 ⇒ yes。⛔ 不要继承本简报任何一句作为结论。
⚠️ 提醒：本卡卡片自己说「Test-only」。若你的交付确实止于测试文件，那大概率不是机械下限的任何一条 —— ⛔ 但那是你按实际 diff 判，不是本席替你判；尤其若你为了让桩可复用而新导出了什么（一个共享 fixture、一个 helper），那就另说。

⭐ 载体预授权：固定拼写行必须落在这条 claim 评论里，而本席 MCP 面上没有编辑评论的工具（按枚举确认）。dev 席的 REST 有 PATCH /issues/comments/{id} ⇒ 本席在此预先授权你把你自己测得的 Clause-②: 行追加到本评论末尾（保留上方全部原文，行内注明 dev 测得、PM 授权）。⚠️ 拼写按字节核对再发：行首 Clause-②:、ASCII 冒号 0x3a（⛔ 不是全角）、token 紧跟。⛔ 绝不另发第二条 claim 评论。

⚠️ 若判 no，本 PR 可以真的落地（当前有 9 个 PR 停靠在契约档位上，fable 连续 19 次 429）。⛔ 但这不构成把它判成 no 的理由 —— 按 diff 判，不按方便判。

七、⭐ 枚举，两条轴（⚠️ 位置轴这次有两类载体，都要看）

①内容轴：谁读了你改动说的东西 —— 至少包括 PresenceProvider 的真实导出面、RecordDetailView 那个 .length > 0 读点、以及那两道 vi.mock 门。
②位置轴：⚠️ 本班刚踩实的一条，务必两类都查：

• (i) 散文/注释里的 file:line 引用 —— scripts/cross-file-line-citation-census.mjs（report-only、五种语法）看得见。在分支点与你的分支上各跑一次做机械对照。⭐ 更强的形式（feat(types): declare drillDown / title / compareTo on both published copies of ObjectChartSchema (objectui#8885) #8895 的席位做出来的）：在 origin/main 本身跑一次，再在你的分支对 main 的一次真实 git merge --no-ff 的结果树上跑一次（一次性 detached worktree —— git merge-tree 的归档树不是 git 仓库，普查需要一个）。⇒ 测的是合并那一刻。
• (ii) 嵌在数据结构里、被机器校验的账本键（键本身含行号）—— 普查看不见它。已确证的一个：scripts/check-doc-example-types.mjs 的 UNGATED_EXAMPLES，键是 `${block.file}:${block.line} ${block.symbol}`。⚠️ PR feat(types): declare drillDown / title / compareTo on both published copies of ObjectChartSchema (objectui#8885) #8895 就是因为只做了 (i) 而被 (ii) 打红的。
• ⭐ 分清两类，只修一类：(A) 在 origin/main 上指得准、被你挪偏 ⇒ 本 PR 修；(B) 本来就指不准 ⇒ ⛔ 不碰，归 objectui#8875。判法是找锚点，⛔ 不是比行号。⛔ CHANGELOG.md 里的行号一律不碰。

八、⛔ 红线

⛔ 不动那 9 个已经正确的文件 · ⛔ 不静默翻转任何既有断言 · ⛔ 不扩展任何 vi.mock 门（测了报告即可）· ⛔ 不改 PresenceProvider 或 RecordDetailView 的产品代码（本卡是 test-infra；若你测到产品代码本身有缺陷，停下来报告）。
⛔ 绝不编辑共享主检出（用专属 worktree）· ⛔ 绝不 git stash · ⛔ 绝不按名杀进程 · ⛔ 不碰 content/docs/releases/ · ⛔ 不碰 governed surface · ⛔ 不扩范围。

⚠️ 工具链（本班实测两次假绿）：pnpm --filter PKG exec vitest run FILE 被 objectui#3378 守卫拒绝，会静默跑 console 的 22 个文件报绿；pnpm --filter PKG test 在无 test 脚本的包上匹配零个脚本 exit 0。⛔ 都不是读数。从仓根：pnpm exec vitest run packages/PKG/src/FILE。
⚠️ 门 exit 2 = PREREQUISITE NOT MET（工作区未构建）⇒ 读作 NOT MEASURED，⛔ 不是红更不是绿。
⚠️ check-clause2-carriers.mjs 的裸 CLI 读的是 objectstack：本仓核对必须 PM_SWEEP_REPO=objectstack-ai/objectui。
⚠️ 共享身份 os-zhuang 的 GitHub API 间歇性限流 —— git 能答的走 git；⛔ 永不在循环里重试。

---

Clause-②: no

⭐ 上行由 dev 席测得并追写，PM 在本评论第六节预授权（REST PATCH /issues/comments/5608746640）；上方全部原文未动。判据：交付 diff = 13 行 *.test.tsx 改动 + 1 份 changeset，无新导出符号、无已发布载荷上的新键、无 schema 键 / 闭集成员 / 注册表项。实测而非断言：各包 files[] 发运 dist，而树中没有任何一份已构建 dist 含 *.test.* 产物（正控：已发布符号 useRecordPresence 确在 packages/collaboration/dist 中）。PR: #8902。

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 8083,
  "status": "done",
  "branch": "claude/issue-8083-record-presence-stub-shape",
  "pr": "https://github.com/objectstack-ai/objectui/pull/8902",
  "premise_still_valid": true,
  "summary": "Both halves done. First half: the 13 RecordDetailView test files that stubbed useRecordPresence as { viewers: [], others: [] } now stub [], matching the 9 that already did; the 9 were not touched. 13 one-line edits plus one empty-frontmatter changeset, nothing else. The card's premise held in full — the hook returns PresenceUser[], its only consumer reads recordPresence.length > 0, and { viewers, others } exists nowhere in this repo as a real shape. Second half (the actual work): measured, and it came out EMPTY — no assertion in any of the 13 was relying on the row being unrenderable, so no existing assertion was flipped, silently or otherwise. The 13th file, expandFls-7230, never fires the probe because its 6 cases resolve while RecordDetailView is still in the isLoading skeleton, an early return above the presence chrome; proven to be a property of the file and not of the stub by appending a one-shot case that awaits the loaded tree (7/7 green). Clause-②: no, judged from the diff; the fixed-spelling line was appended to claim comment 5608746640 under the PM's pre-authorisation in its section six, all original text preserved.",
  "tests": "Final commit 7dba761a5; every heavy run through scripts/pm/os-verify-lock.sh, verdicts quoted from the runner's own VERDICT line, never a bare $?. (1) CLASS JUDGEMENT — can it now go red, a mutation measurement, not a green run. Probe = stub fed one PresenceUser + a PresenceAvatars stand-in that throws OS8083_PROBE_ROW_RENDERED. Positive control FIRST on the 9 correct files: 9/9 files red, 46 cases, every failure the probe's own error — probe validated before it was used as an instrument. BEFORE on the 13, object stub filled in BOTH fields ({ viewers: [u], others: [u] }): 'Test Files 13 passed (13) / Tests 99 passed (99)', ZERO probe fires — no value can render the row. AFTER on the 13, array stub filled: 'Test Files 12 failed | 1 passed (13) / Tests 86 failed | 13 passed (99)'. The tree as shipped, all 22 with []: 'Test Files 22 passed (22) / Tests 157 passed (157)' — byte-identical to the pre-fix baseline, which is exactly why that green carries no discriminating power and is not offered as evidence. (2) SECOND HALF — the PresenceAvatars override line was DELETED rather than restubbed, so the real component came through the factory's importOriginal spread and rendered its actual DOM with a real PresenceUser: all 22 files 157/157 green. Guarded against a vacuous green by a two-legged control on headerRefresh: with the mutation an appended case asserting the real component's role=group stack passes (6/6); without it the same case fails with 'expected 0 to be greater than 0'. So the element counted is exclusively the real PresenceAvatars. (3) ABLATION — prediction written to disk BEFORE the run: ablate headerRefresh alone back to the object shape, array stub everywhere else, 20 of 22 red, the two green being headerRefresh (ablated) and expandFls-7230 (never reaches the loaded tree), nothing else moving. Observed exactly: 'Test Files 20 failed | 2 passed (22) / Tests 128 failed | 29 passed (157)', the two green files exactly those. Every mutation leg proves it landed on disk before anything runs (injected-marker count, removed-marker count, git hash-object before/after) and every restore is verified by git diff HEAD empty AND the blob hash back to its HEAD value (c44714e63278), never by an exit code; all probe scripts carry a trap on EXIT INT TERM calling a restore function with absolute paths. One early leg refused to proceed (regex typo, 'MUTATION DID NOT LAND') and was reported as a void reading rather than silently retried. (4) GATES at final HEAD, exit codes captured before any pipe: check:vi-mock-specifiers 0, check:vi-mock-inherit 0, check:control-bytes 0 ('scanned 7085 tracked text file(s)'), changeset:check 0 ('No changeset declares a major bump'). pnpm --filter @object-ui/app-shell run type-check (tsc --noEmit && tsc -p tsconfig.test.json, so the test files ARE covered) exit 0 — its FIRST attempt returned exit 2 with \"Cannot find module '@object-ui/fields'\", an unbuilt workspace, read as NOT MEASURED and re-run after pnpm --filter '@object-ui/app-shell^...' build. pnpm --filter @object-ui/app-shell run lint: exit 0, '2943 problems (0 errors, 2943 warnings)', all pre-existing. check-governed-queue-guard --test over all 14 paths: NOT GOVERNED. (5) DECLARED NARROWING — vitest's own config collects 669 test files for packages/app-shell/; this branch ran 22 of them (count from vitest's own Test Files line) plus the whole package's type-check and lint. The narrowing excludes nothing that could move: a vi.mock factory is scoped to the file that declares it, each of the 13 is an import leaf (nothing in the tree imports any of them), and every touched file kept its exact line count. A 37-file presence-consumer radius was queued for the shared lock TWICE and returned exit 99 / queue-timeout both times behind a sibling holder at 18+ minutes — NOT MEASURED, neither green nor red; the interval was spent on lock-free work (PR body, changeset, position-axis census) and the slot was re-taken by name rather than re-queued from the back. CI runs the full farm.",
  "mcp_calls": "0 — the whole run used the zero-quota page-payload channel for the card and plain REST for every write; no MCP GitHub tool was invoked.",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: the two vi.mock gates are BLIND to this class, measured rather than inferred — with all 13 object-shaped stubs put back on disk, check:vi-mock-specifiers and check:vi-mock-inherit print the same verdict lines and the same exit 0 as on the repaired tree. check:vi-mock-specifiers judges whether a RELATIVE specifier resolves (these mock the bare '@object-ui/collaboration', which its own summary counts as '935 bare (out of scope)'); check:vi-mock-inherit judges whether the factory OBTAINS the real module, and all 13 already spread importOriginal and always did. Neither judges an override's VALUE. Not filed because an absence of enforcement is an observation, not one of the three filing classes; the PM's brief names the gate extension as a separate card and forbade extending either gate here. Carrier: the PM seat, which asked for this reading explicitly. Full text in the PR's 验收备注.",
    "noted, not filed: RecordDetailView.expandFls-7230.test.tsx observes nothing of the rendered tree — its 6 cases resolve as soon as a findOne is recorded, which happens while RecordDetailView is still in the isLoading skeleton (an early return above the presence chrome), so the whole loaded tree is outside every case's window. Not a defect: the file is about the $expand payload and asserts on it correctly. It matters only as a reading — the file's presence stub is now capable (proven: with a one-shot appended case that awaits the loaded tree, the presence element IS found, 7/7 green), so a future DOM assertion added there would need its own await. Carrier: the next PR that adds a DOM assertion to that file.",
    "noted, not filed: no line-addressed citation into any of the 13 exists anywhere in the tree, and the confirmed machine-checked ledger UNGATED_EXAMPLES (scripts/check-doc-example-types.mjs, 90 rows) addresses app-shell zero times — so carrier (ii) of the position axis is empty for this diff. Swept for the class rather than the instance: the only other literal path:NUMBER entries in the tree are skills/objectui/guides/* fixtures inside scripts/__tests__/. Carrier: none — recorded so the next seat need not re-derive it."
  ]
}

---

Generated by Claude Code