@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-audit': patch
+---
+
+plugin-audit: a mention notification reaches a mentioned user only when they may read the comment it previews, as well as the record it links
+
+Clause-②: no
+Metadata-protocol: none
+
+The `@mention` recipient gate decided each mentioned user on one read: may they open the record the comment is on. The notification also carries a preview of the comment's text, and being able to read a record does not mean being able to read its comments, because the comment object has its own object-level grant, tenant wall and row scope. The gate now also runs each recipient's own read of the comment, by id. It uses the same evaluator as the comment read path (`resolveReadableParentIds`, in the recipient's resolved envelope), and it withholds the notification when that read does not return the comment. Each withheld recipient is logged at `warn` with a new reason: `cannot_read_thread`, or `no_comment_id` when the comment has no id to read it by. The comment text is never logged.
+
+For administrators: a mentioned user is notified only when a permission set they hold grants read on comments. To notify a population that should take part in record discussions, grant comment read in a set it holds.
@@ -423,8 +423,8 @@ export class AuditPlugin implements Plugin {
         return typeof tenancy?.defaultOrgId === 'function' ? tenancy.defaultOrgId() : undefined;
       };
       // A mention notification previews its comment and links its record, so
-      // it reaches only a mentioned user who can READ that record — judged in
-      // that user's own envelope, their organization claim vetted under the
+      // it reaches only a mentioned user who can READ both — judged in that
+      // user's own envelope, their organization claim vetted under the
       // posture the request path reads (`mention-recipient-gate.ts`).
       const getTenancyPosture = () => {
         try {
 
@@ -178,10 +178,10 @@ export interface AuditWriterOptions {
   /**
    * The `@mention` recipient gate (`mention-recipient-gate.ts`): the mentioned
    * users who may be notified about a comment — each resolved to a user id,
-   * minus the author, minus everyone who cannot READ the comment's record.
-   * AuditPlugin wires the real gate. Absent → no mention notification is
-   * emitted at all (fail closed, said once): the writer cannot tell on its own
-   * who may see the record a notification would preview.
+   * minus the author, minus everyone who cannot READ the comment's record or
+   * the comment itself. AuditPlugin wires the real gate. Absent → no mention
+   * notification is emitted at all (fail closed, said once): the writer cannot
+   * tell on its own who may see the comment a notification would preview.
    */
   admitMentionRecipients?(input: MentionGateInput): Promise<string[]>;
 }
@@ -2529,7 +2529,7 @@ export function installAuditWriters(
   /**
    * M10.8: Dedicated hook on `sys_comment` afterInsert that parses the
    * `mentions` JSON field and writes one sys_notification per mentioned
-   * user who can read the comment's record (`admitMentionRecipients`).
+   * user who can read the comment and its record (`admitMentionRecipients`).
    * Lives outside `writeAudit` because sys_comment is in
    * SKIP_OBJECTS (we don't want audit/activity rows for comments —
    * those have their own first-class feed).
@@ -2565,9 +2565,9 @@ export function installAuditWriters(
     const commentId = row.id != null ? String(row.id) : null;
 
     // The notification is a copy of the comment (its preview) and a link to
-    // the record, so it reaches only a mentioned user who can READ that
-    // record — never a raw id or email from the client-written list. The
-    // author is dropped there too.
+    // the record, so it reaches only a mentioned user who can READ both the
+    // comment and that record — never a raw id or email from the
+    // client-written list. The author is dropped there too.
     if (!opts.admitMentionRecipients) {
       if (!warnedNoMentionGate) {
         warnedNoMentionGate = true;
 
@@ -249,8 +249,8 @@ const READ_OPS = new Set(['find', 'findOne', 'count', 'aggregate']);
  * `{ id: '__deny_all__' }` read-filter deny). */
 const READ_DENY_ALL = { id: '__comment_thread_denied__' } as const;
 
-/** The object a reaction's access derives from. */
-const COMMENT_OBJECT = 'sys_comment';
+/** The object a reaction's access derives from, and the one a mention notification previews. */
+export const COMMENT_OBJECT = 'sys_comment';
 
 /**
  * A comment's emoji reactions — one row per (comment, emoji, user), the
 
@@ -2,19 +2,21 @@
 
 /**
  * A `collab.mention` notification reaches a mentioned user only when that user
- * can READ the record the comment is about (`mention-recipient-gate.ts`).
+ * can READ both the comment it previews and the record it links
+ * (`mention-recipient-gate.ts`).
  *
  * ## What is real
  *
  * The kernel, ObjectQL, a real SQLite driver, `AuditPlugin` (its comment write
- * gates and its mention writer, wired with the real recipient gate), the
- * identity rows (`sys_user`, `sys_member` — the platform's own object
- * definitions) and the grant resolution over them (`resolveUserAuthzGrants`,
- * `vetOrganizationClaim`, `resolveReadableParentIds` from `@objectstack/core`).
- * Every comment is inserted through the engine as its author, so the comment
- * write gates run and the mention writer fires from the real `afterInsert`.
+ * gates, its comment read gate and its mention writer, wired with the real
+ * recipient gate), the identity rows (`sys_user`, `sys_member` — the
+ * platform's own object definitions) and the grant resolution over them
+ * (`resolveUserAuthzGrants`, `vetOrganizationClaim`, `resolveReadableParentIds`
+ * from `@objectstack/core`). Every comment is inserted through the engine as
+ * its author, so the comment write gates run and the mention writer fires from
+ * the real `afterInsert`.
  *
- * ## The two stand-ins
+ * ## The three stand-ins
  *
  * - plugin-security's read enforcement on the record object, played by ONE
  *   engine middleware: the ADR-0093 tenant wall (`isolated`: the caller's
@@ -24,19 +26,27 @@
  *   plugin-security's to pin; what is pinned HERE is that the gate asks the
  *   read in the mentioned user's own envelope, with their organization claim
  *   vetted — the stand-in admits whatever envelope it is handed.
+ * - plugin-security's object-level read grant on `sys_comment`, played by a
+ *   second middleware: a caller whose envelope holds the `comment_reader`
+ *   position may read comments, and any other caller's read is refused the way
+ *   the real layer refuses it — a throw. It stands in for "the set this
+ *   position distributes grants read on comments". ALICE, CAROL and BOB hold
+ *   the position, each in their own organization; DAVE, a member of ORG_A like
+ *   CAROL, does not — so he reads the open record and not its comments.
  * - the `messaging` service, played by a recorder of `emit()` calls (the
  *   inbox materialisation is service-messaging's to pin).
  *
  * plugin-security also owns the two grant tables the resolver reads beside
  * `sys_member` (`sys_user_position`, `sys_user_permission_set`). They are
- * registered here with the columns the resolver reads and left EMPTY — no
- * user holds a position or a permission set, so membership alone decides the
+ * registered here with the columns the resolver reads. `sys_user_position`
+ * carries the `comment_reader` assignments above and nothing else, and
+ * `sys_user_permission_set` is left EMPTY, so membership alone decides the
  * wall. Unregistered, the resolver refuses (an unreadable authorization store
  * is an outage, not a denial) and the gate withholds every notification.
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
-import { ObjectKernel, type Plugin, type PluginContext } from '@objectstack/core';
+import { ObjectKernel, resolveUserAuthzGrants, type Plugin, type PluginContext } from '@objectstack/core';
 import { ObjectQL, ObjectQLPlugin } from '@objectstack/objectql';
 import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
 import { SysMember, SysUser } from '@objectstack/platform-objects/identity';
@@ -56,6 +66,10 @@ const ALICE = { id: 'u_alice', email: 'alice@a.test' };
 const CAROL = { id: 'u_carol', email: 'carol@a.test' };
 /** A member of ORG_B only. */
 const BOB = { id: 'u_bob', email: 'bob@b.test' };
+/** A fellow member of ORG_A who reads every non-confidential task there, and holds no read on comments. */
+const DAVE = { id: 'u_dave', email: 'dave@a.test' };
+/** The position whose holders the comment stand-in lets read comments — assigned through `sys_user_position`. */
+const COMMENT_READER_POSITION = 'comment_reader';
 
 type Posture = 'single' | 'isolated' | 'group';
 const tenancy: { posture: Posture } = { posture: 'isolated' };
@@ -79,6 +93,19 @@ function enforcement(context: any): Record<string, unknown> {
   return { $and: clauses };
 }
 
+/**
+ * plugin-security's object-level read grant on `sys_comment`, as the module
+ * header sets out: read off the caller's envelope, refused by a throw.
+ */
+function assertReadsComments(context: any): void {
+  const positions: unknown = context?.positions;
+  if (Array.isArray(positions) && positions.includes(COMMENT_READER_POSITION)) return;
+  const err: any = new Error('stand-in: no read grant on sys_comment');
+  err.code = 'PERMISSION_DENIED';
+  err.status = 403;
+  throw err;
+}
+
 const emits: Array<Record<string, any>> = [];
 
 function standIns(): Plugin {
@@ -106,29 +133,39 @@ function standIns(): Plugin {
 const authorContext = () => ({
   userId: ALICE.id,
   tenantId: ORG_A,
-  positions: ['org_member'],
+  positions: ['org_member', COMMENT_READER_POSITION],
   permissions: [],
   accessible_org_ids: [ORG_A],
 });
 
-describe('@mention notifications reach only mentioned users who can read the record', () => {
+describe('@mention notifications reach only mentioned users who can read the comment and its record', () => {
   let kernel: ObjectKernel;
   let engine: ObjectQL;
   let openTask: string;
   let confidentialTask: string;
   let seq = 0;
 
-  /** Post a comment on `taskId` as ALICE, mentioning `mentions`; the mention emits it produced. */
-  const comment = async (taskId: string, mentions: unknown[]) => {
-    emits.length = 0;
+  /** Post a comment on `taskId` as ALICE, mentioning `mentions`; the stored row. */
+  const post = async (taskId: string, mentions: unknown[]): Promise<Record<string, any>> => {
     seq += 1;
-    await engine.insert(
+    return engine.insert(
       'sys_comment',
       { thread_id: `${TASK}:${taskId}`, body: `note ${seq}`, mentions: JSON.stringify(mentions) },
       { context: authorContext() },
     );
+  };
+  /** Post a comment on `taskId` as ALICE, mentioning `mentions`; the mention emits it produced. */
+  const comment = async (taskId: string, mentions: unknown[]) => {
+    emits.length = 0;
+    await post(taskId, mentions);
     return emits.filter((e) => e.topic === 'collab.mention');
   };
+  /** `user`'s own read of the comment `commentId`, in the envelope the request path gives them. */
+  const readCommentAs = (user: { id: string }, positions: string[], commentId: string) =>
+    engine.find('sys_comment', {
+      where: { id: commentId },
+      context: { userId: user.id, tenantId: ORG_A, positions, permissions: [], accessible_org_ids: [ORG_A] },
+    });
   const audiences = (events: Array<Record<string, any>>) => events.map((e) => e.audience);
 
   beforeAll(async () => {
@@ -180,13 +217,24 @@ describe('@mention notifications reach only mentioned users who can read the rec
       }
       return next();
     }, { object: TASK });
+    engine.registerMiddleware(async (op: any, next: () => Promise<void>) => {
+      if (READ_OPS.has(op.operation) && op.ast && !op.context?.isSystem) assertReadsComments(op.context);
+      return next();
+    }, { object: 'sys_comment' });
 
-    for (const u of [ALICE, CAROL, BOB]) {
+    for (const u of [ALICE, CAROL, BOB, DAVE]) {
       await engine.insert('sys_user', { id: u.id, name: u.id, email: u.email }, { context: SYS });
     }
-    for (const [user, org] of [[ALICE, ORG_A], [CAROL, ORG_A], [BOB, ORG_B]] as const) {
+    for (const [user, org] of [[ALICE, ORG_A], [CAROL, ORG_A], [BOB, ORG_B], [DAVE, ORG_A]] as const) {
       await engine.insert('sys_member', { user_id: user.id, organization_id: org, role: 'member' }, { context: SYS });
     }
+    for (const [user, org] of [[ALICE, ORG_A], [CAROL, ORG_A], [BOB, ORG_B]] as const) {
+      await engine.insert(
+        'sys_user_position',
+        { user_id: user.id, organization_id: org, position: COMMENT_READER_POSITION },
+        { context: SYS },
+      );
+    }
     openTask = (await engine.insert(TASK, { name: 'open', organization_id: ORG_A, owner_id: ALICE.id, confidential: false }, { context: SYS })).id;
     confidentialTask = (
       await engine.insert(TASK, { name: 'confidential', organization_id: ORG_A, owner_id: ALICE.id, confidential: true }, { context: SYS })
@@ -257,20 +305,77 @@ describe('@mention notifications reach only mentioned users who can read the rec
     });
   });
 
-  it('logs each withheld recipient with the user id and the reason, never the comment text', async () => {
-    const warned: Array<{ message: string; meta?: Record<string, unknown> }> = [];
-    const admitted = await admitMentionRecipients(
-      {
-        engine: engine as any,
-        getTenancyPosture: () => 'isolated',
-        logger: { warn: (message, meta) => warned.push({ message, meta }) },
-      },
-      { mentions: [BOB.id, CAROL.id, 'nobody@nowhere.test'], threadId: `${TASK}:${openTask}`, actorId: ALICE.id, organizationId: ORG_A, commentId: 'c1' },
-    );
-    expect(admitted).toEqual([CAROL.id]);
-    expect(warned.map((w) => w.meta)).toEqual([
-      { reason: 'unknown_email', commentId: 'c1' },
-      { reason: 'cannot_read_source', userId: BOB.id, commentId: 'c1' },
-    ]);
+  describe('the comment itself must be readable, not only its record', () => {
+    it('control: the resolver projects the comment grant to CAROL and not to DAVE; both read the record, only CAROL its comment', async () => {
+      const carol = await resolveUserAuthzGrants(engine, CAROL.id, { tenantId: ORG_A });
+      const dave = await resolveUserAuthzGrants(engine, DAVE.id, { tenantId: ORG_A });
+      expect(carol.positions).toContain(COMMENT_READER_POSITION);
+      expect(dave.positions).not.toContain(COMMENT_READER_POSITION);
+
+      const asDave = await engine.find(TASK, { where: { id: openTask }, context: { userId: DAVE.id, tenantId: ORG_A } });
+      expect(asDave.map((r: any) => r.id)).toEqual([openTask]);
+
+      const row = await post(openTask, []);
+      expect((await readCommentAs(CAROL, carol.positions, String(row.id))).map((r: any) => r.id)).toEqual([row.id]);
+      await expect(readCommentAs(DAVE, dave.positions, String(row.id))).rejects.toMatchObject({
+        code: 'PERMISSION_DENIED',
+        status: 403,
+      });
+    });
+
+    it('withholds the notification from a mentioned user who may read the record but not the comment, by id or by email', async () => {
+      expect(audiences(await comment(openTask, [DAVE.id]))).toEqual([]);
+      expect(audiences(await comment(openTask, [DAVE.email]))).toEqual([]);
+    });
+
+    it('notifies the mentioned user who may read both, and never the author', async () => {
+      const events = await comment(openTask, [DAVE.id, CAROL.id, ALICE.id]);
+      expect(audiences(events)).toEqual([[CAROL.id]]);
+      expect(events[0]).toMatchObject({ source: { object: TASK, id: openTask }, payload: { body: `note ${seq}` } });
+    });
+
+    it('holds under the single posture as under a wall', async () => {
+      tenancy.posture = 'single';
+      expect(audiences(await comment(openTask, [DAVE.id, DAVE.email, CAROL.id]))).toEqual([[CAROL.id]]);
+    });
+  });
+
+  describe('the withheld-recipient log', () => {
+    const gate = (warned: Array<{ message: string; meta?: Record<string, unknown> }>) => ({
+      engine: engine as any,
+      getTenancyPosture: () => 'isolated' as const,
+      logger: { warn: (message: string, meta?: Record<string, unknown>) => warned.push({ message, meta }) },
+    });
+
+    it('logs each withheld recipient with the user id and the reason, never the comment text', async () => {
+      const row = await post(openTask, []);
+      const commentId = String(row.id);
+      const warned: Array<{ message: string; meta?: Record<string, unknown> }> = [];
+      const admitted = await admitMentionRecipients(gate(warned), {
+        mentions: [BOB.id, DAVE.id, CAROL.id, 'nobody@nowhere.test'],
+        threadId: `${TASK}:${openTask}`,
+        actorId: ALICE.id,
+        organizationId: ORG_A,
+        commentId,
+      });
+      expect(admitted).toEqual([CAROL.id]);
+      expect(warned.map((w) => w.meta)).toEqual([
+        { reason: 'unknown_email', commentId },
+        { reason: 'cannot_read_source', userId: BOB.id, commentId },
+        { reason: 'cannot_read_thread', userId: DAVE.id, commentId },
+      ]);
+      expect(JSON.stringify(warned)).not.toContain(String(row.body));
+    });
+
+    it('withholds every recipient when the comment cannot be read back by its id', async () => {
+      const warned: Array<{ message: string; meta?: Record<string, unknown> }> = [];
+      const input = { mentions: [CAROL.id], threadId: `${TASK}:${openTask}`, actorId: ALICE.id, organizationId: ORG_A };
+      expect(await admitMentionRecipients(gate(warned), input)).toEqual([]);
+      expect(await admitMentionRecipients(gate(warned), { ...input, commentId: 'cmt_never_written' })).toEqual([]);
+      expect(warned.map((w) => w.meta)).toEqual([
+        { reason: 'no_comment_id', userId: CAROL.id },
+        { reason: 'cannot_read_thread', userId: CAROL.id, commentId: 'cmt_never_written' },
+      ]);
+    });
   });
 });