fix(plugin-audit): describe sys_comment reactions and mentions by the shape they store (#20558) (#20605)

Fixes #20558

Clause-②: no

The `description` of two `sys_comment` fields is served metadata (field
help, and what an AI client reads before it seeds a comment). Both named
a shape no producer writes. They now name the stored shape, and the `en`
translation bundle is regenerated from the source.

| Field | Description was | Description is now |
| --- | --- | --- |
| `reactions` | `JSON array of emoji reaction objects` | `JSON object
mapping each emoji to the list of user ids who reacted` |
| `mentions` | `JSON array of @mention objects` | `JSON array of the
user ids @mentioned in the comment` |

Files: `packages/plugins/plugin-audit/src/objects/sys-comment.object.ts`
(2 lines),
`packages/plugins/plugin-audit/src/translations/en.objects.generated.ts`
(regenerated),
`.changeset/20558-comment-reactions-mentions-description.md` (patch on
`@objectstack/plugin-audit`). Landing point is the one the card names;
no producer lives in another package of this repository.

## Measurement (premise check, before the edit)

Trees read: objectstack `c876a742` (this PR's base) and objectui
`bf7ab35c` (a read-only shallow clone made through the session git
proxy; the REST API answers 403 for that repository, plain git does
not).

- `reactions`, this repository: no producer or reader. `git grep -i
reactions` over the tree, minus CHANGELOGs and generated bundles, finds
only the field declaration, ADR and docs prose, and unrelated
`enableReactions` UI props.
- `reactions`, objectui
`packages/app-shell/src/views/RecordDetailView.tsx`: `parseReactions`
reads a JSON object of `emoji -> string[]`, and the click handler writes
`JSON.stringify(storedReactions(...))`, the same map (`storedReactions`
returns a string-keyed map of string arrays).
`packages/collaboration/src/CommentThread.tsx` types it as a
string-keyed map of string arrays. The card's premise holds.
- `mentions`, producer: the same file's `handleAddComment` and
`handleAddReply` (the only two `sys_comment` creates in objectui) write
`mentions: JSON.stringify(mentionIds)`, and `extractMentions` in
`packages/plugin-detail/src/extractMentions.ts` returns a de-duplicated
`string[]` of user ids. No objects. This disagrees with the old
sentence, so per the triage rule `mentions` rides in this PR.
- `mentions`, consumer in this repository: `writeCommentMentions` in
`packages/plugins/plugin-audit/src/audit-writers.ts` reads the JSON and
accepts an array of id strings or an array of objects with an `id` key.
Every in-repo test value is an id string (`'["user-2"]'`). The
description names only the one shape the producer writes; the consumer's
object tolerance is not advertised (one strict contract, not two
dialects).
- Not measured: any producer outside objectstack and objectui (the
`cloud` repository was not read); a runtime probe of what the console
shows for the old array shape (the card marks that step as read
inference, and it stays so).

## Translations

`node scripts/check-i18n-bundles.mjs --write` rewrote only
`en.objects.generated.ts`. The other eight packages regenerated with no
diff. The `zh-CN`, `ja-JP` and `es-ES` bundles keep their hand-written
values (merge mode), and `pnpm check:i18n` and `pnpm
check:i18n-stale-fill` are green without touching them, so per the
dispatch they are not hand-translated here. Six strings therefore still
say "array of ... objects" and now contradict the English: `mentions`
and `reactions` `help` in each of the three locales (`zh-CN` lines 218
and 222, `ja-JP` lines 218 and 222, `es-ES` lines 218 and 222). This is
listed in the report as an open question for the PM seat.

## Verification (final head e83328b)

- Derived gate list: `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` gives 57 commands (the seat's 50 plus
7 that the changeset file adds). All 57 were run one by one with the
exit code captured first; all exit 0 at `e83328b6`. `--ran`
reconciliation with exit codes: 57 derived, 57 run, 0 NOT-MEASURED, 0
UNRUN. One first attempt of `pnpm check:dual-build-cjs-loads` exited 3
(PREREQUISITE NOT MET: nine unrelated packages had no `dist/`); after
building those nine it exited 0 (104 entry points, 66 packages).
- `pnpm --filter @objectstack/plugin-audit test`: 25 files, 363 tests
passed. `pnpm --filter @objectstack/plugin-audit typecheck`: exit 0
(both run at `236bae38`; the one later commit changes only the changeset
text).
- One-time ablation (nothing kept): with the `en` bundle put back to the
base text, on-disk mutation confirmed by grep (old text 1, new text 0),
`node scripts/check-i18n-bundles.mjs --filter=audit` exits 1 with
`plugins/plugin-audit DRIFTED (1)`. Restored with `git checkout HEAD --
path`; the blob hash matches HEAD (`7c457527...`) and `git diff HEAD` is
empty. Direction observed: red, as expected.
- Line budget: 20 additions, 4 deletions, 3 files; no `skills/**` file
touched.

## Acceptance notes

- The one open item is the three stale translated locales above; nothing
else is left out of scope.

## Seat append — patch round 1 (head `0cebc286`, the dev's text,
appended by the `domain:services` seat)

The seat answered the open question above with option A, so the six
translated help strings are rewritten on this branch. This section
supersedes the Translations and Acceptance notes paragraphs above where
they call the three locales stale.

Values only: no key added or dropped, no `label` and no other string
touched. Exactly six `help` values changed (two per file, 6 additions
and 6 deletions):

| Locale | `mentions` help | `reactions` help |
| --- | --- | --- |
| `zh-CN` | `评论中被 @ 提及的用户 ID 的 JSON 数组` | `将每个表情映射到对其做出回应的用户 ID 列表的 JSON
对象` |
| `ja-JP` | `コメント内で @メンションされたユーザー ID の JSON 配列` | `各絵文字を、リアクションしたユーザー ID
のリストに対応付ける JSON オブジェクト` |
| `es-ES` | `Matriz JSON de los id de usuario mencionados con @ en el
comentario.` | `Objeto JSON que asigna cada emoji a la lista de id de
usuario de quienes reaccionaron.` |

Wording follows each bundle's own habits: the terms for a user id match
the existing `user_id` help in the same file, `es-ES` keeps its trailing
period as 20 of its 23 help strings do, and `zh-CN` and `ja-JP` stay
period-free. The faithfulness of the translations was read by the author
only, with no native-speaker review.

The changeset gains one clause saying the translated help texts follow;
the level stays `patch`.

Proof the tool keeps them: after the edit was committed, `node
scripts/check-i18n-bundles.mjs --write` regenerated all nine packages
and left `git status --porcelain` empty and `git diff HEAD` at zero
lines. Against the previous head, the diff of the three translation
files is those six `help` lines and nothing else.

At head `0cebc286`: `pnpm check:i18n`, `pnpm check:i18n-stale-fill` and
`pnpm check:nul-bytes` exit 0, `pnpm --filter @objectstack/plugin-audit
test` passes (25 files, 363 tests), and all 57 derived gate commands
exit 0 (the derived list is unchanged by this round; `--ran`
reconciliation: 57 run, 0 NOT-MEASURED). Whole-PR diff: 6 files, 26
additions, 10 deletions.

### Seat append — Acceptance notes (added at the at-tier review's
request, record `5885205176`)

- **Noted, not filed:** the in-repo consumer `writeCommentMentions`
(`plugin-audit` `audit-writers.ts`) also accepts array entries that are
objects with an `id` key, a lenient-consumer tolerance that no producer
in this repository writes. This PR deliberately does not advertise it:
the new description names only the id-string array. No public door
answers wrong today, so it is not a card. Dedupe words:
`writeCommentMentions object entries` · `sys_comment mentions id objects
tolerance` · `collab.mention parse leniency`.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/20558-comment-reactions-mentions-description.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/plugin-audit': patch
+---
+
+`sys_comment.reactions` and `sys_comment.mentions` now describe the shape they actually store (#20558)
+
+The two field descriptions are served metadata (field help in the console, and what an AI client reads before it seeds a comment), and both named a shape no producer writes:
+
+| Field | Description was | Description is now | Stored value |
+| --- | --- | --- | --- |
+| `reactions` | `JSON array of emoji reaction objects` | `JSON object mapping each emoji to the list of user ids who reacted` | `{"👍":["usr_1","usr_2"]}` |
+| `mentions` | `JSON array of @mention objects` | `JSON array of the user ids @mentioned in the comment` | `["usr_1","usr_2"]` |
+
+The console's record discussion panel reads and writes `reactions` as that map, and writes `mentions` as that list of ids; the `collab.mention` notification hook reads the ids.
+
+Description text only: no stored value, validation rule or hook changes, and nothing to migrate. The English translation bundle is regenerated from the source description, and the zh-CN, ja-JP and es-ES help texts for both fields are rewritten to match (values only, no key added or dropped).

packages/plugins/plugin-audit/src/objects/sys-comment.object.ts

@@ -118,14 +118,14 @@ export const SysComment = ObjectSchema.create({
     mentions: Field.textarea({
       label: 'Mentions',
       required: false,
-      description: 'JSON array of @mention objects',
+      description: 'JSON array of the user ids @mentioned in the comment',
       group: 'Body',
     }),
 
     reactions: Field.textarea({
       label: 'Reactions',
       required: false,
-      description: 'JSON array of emoji reaction objects',
+      description: 'JSON object mapping each emoji to the list of user ids who reacted',
       group: 'Body',
     }),
 

packages/plugins/plugin-audit/src/translations/en.objects.generated.ts

@@ -215,11 +215,11 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       mentions: {
         label: "Mentions",
-        help: "JSON array of @mention objects"
+        help: "JSON array of the user ids @mentioned in the comment"
       },
       reactions: {
         label: "Reactions",
-        help: "JSON array of emoji reaction objects"
+        help: "JSON object mapping each emoji to the list of user ids who reacted"
       },
       is_edited: {
         label: "Edited"

packages/plugins/plugin-audit/src/translations/es-ES.objects.generated.ts

@@ -215,11 +215,11 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       mentions: {
         label: "Menciones",
-        help: "Matriz JSON de objetos @mention."
+        help: "Matriz JSON de los id de usuario mencionados con @ en el comentario."
       },
       reactions: {
         label: "Reacciones",
-        help: "Matriz JSON de objetos de reacción emoji."
+        help: "Objeto JSON que asigna cada emoji a la lista de id de usuario de quienes reaccionaron."
       },
       is_edited: {
         label: "Editado"

packages/plugins/plugin-audit/src/translations/ja-JP.objects.generated.ts

@@ -215,11 +215,11 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       mentions: {
         label: "メンション",
-        help: "@メンションオブジェクトの JSON 配列"
+        help: "コメント内で @メンションされたユーザー ID の JSON 配列"
       },
       reactions: {
         label: "リアクション",
-        help: "絵文字リアクションオブジェクトの JSON 配列"
+        help: "各絵文字を、リアクションしたユーザー ID のリストに対応付ける JSON オブジェクト"
       },
       is_edited: {
         label: "編集済み"

packages/plugins/plugin-audit/src/translations/zh-CN.objects.generated.ts

@@ -215,11 +215,11 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       mentions: {
         label: "提及",
-        help: "@mention 对象的 JSON 数组"
+        help: "评论中被 @ 提及的用户 ID 的 JSON 数组"
       },
       reactions: {
         label: "回应",
-        help: "表情回应对象的 JSON 数组"
+        help: "将每个表情映射到对其做出回应的用户 ID 列表的 JSON 对象"
       },
       is_edited: {
         label: "已编辑"