@@ -0,0 +1,22 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-audit': minor
+'@objectstack/metadata-protocol': minor
+'@objectstack/objectql': minor
+'@objectstack/client': minor
+---
+
+feat(spec): a comment's author is told which @mentioned users will not be notified, and a mention added by editing is notified
+
+Clause-②: yes
+Metadata-protocol: added
+
+The `@mention` recipient gate withholds a notification from a mentioned user who cannot read the comment or its record. Until now it only logged that, so the author believed the person had been told. The comment still saves with every mention; now the requester's own answer says who will not be notified.
+
+- **Spec.** `CreateDataResponseSchema` and `UpdateDataResponseSchema` declare an optional, response-only `withheldMentions`: the ids of the users this write @mentioned whose notification the mention gate withheld. Ids only, never the reason. Only a `sys_comment` write fills it, only on the requester's own answer to that request, and the key is omitted when nobody was withheld. It is not a field of `sys_comment` and is never stored, since a stored member would tell every reader who cannot read the thread. `WriteObservabilityOptions` declares the in-process listener that carries it, `onMentionsWithheld(userIds)`, beside `onFieldsDropped` and `onValidationAdvisory`. Like them it never crosses the wire.
+- **plugin-audit.** The mention writer reports the gate's own verdict to that listener, which it reads off its hook's `ctx.input.options` (the write's own options bag). Readability is not derived a second time, and who the gate admits is unchanged. The writer now also runs on `sys_comment` `afterUpdate`, so a mention added by editing a comment is judged and notified like one written with it. An edit judges only the mentions it added; a mention the comment already carried is not judged or notified again. The editor, who may be a parent-record editor rather than the author, is the actor of an edit's notifications: they are named in the title and never notified themselves. `MentionGateInput` takes an optional `onWithheld(userId)` callback.
+- **metadata-protocol.** `createData` and `updateData` pass the listener and answer the ids as `withheldMentions`. A nested write that a hook or a flow makes inside this one carries its own options, so its verdicts never reach this answer.
+- **client.** `CreateDataResult` and `UpdateDataResult` declare `withheldMentions?: string[]`, mirroring the two schemas.
+- **objectql.** `engine.update` accepts the `onMentionsWithheld` option. The engine never calls it; it carries it to the `after*` hooks with the rest of the caller's bag.
+
+Nothing to do for existing clients: a client that does not read `withheldMentions` sees the same answer as before.
@@ -232,13 +232,23 @@ Create a new record.
 **Body**: `{ name: "Acme Corp", industry: "Technology" }`  
 **Response**: `{ object: "account", id: "1", record: { ... } }`
 
+A `sys_comment` create that @mentions users the server will not notify (the
+mention gate withheld them, most often because they cannot read the comment or
+its record) also answers `withheldMentions`: those users' ids, with no reason, on
+the requester's own answer only. The comment is saved
+with every mention, and nothing about the withheld users is stored on it. With
+nobody withheld, the key is absent.
+
 ### `PATCH /data/:object/:id`
 
 Update an existing record (partial update).
 
 **Body**: `{ industry: "Healthcare" }`  
 **Response**: `{ object: "account", id: "1", record: { ... } }`
 
+A `sys_comment` update answers `withheldMentions` the same way, for the mentions
+the update added. A mention the comment already carried is not judged again.
+
 ### `DELETE /data/:object/:id`
 
 Delete a record.
 
@@ -327,11 +327,13 @@ interface EngineUpdateOptions {
 
 ### WriteObservabilityOptions
 
-The write methods (`insert` / `update`) additionally accept three **in-process**
+The write methods (`insert` / `update`) additionally accept four **in-process**
 options. Two govern what happens when caller-supplied write fields are legally
 stripped from the payload before the driver write: observe the strip
 (`onFieldsDropped`) or refuse the write outright (`strictReadonlyWrites`). The
 third, `onValidationAdvisory`, reports the write's advisory validation-rule hits.
+The fourth, `onMentionsWithheld`, reports the users a comment write @mentioned who
+will not be notified.
 
 The strips these two options cover are the engine's legal ones:
 
@@ -357,6 +359,7 @@ on `insert` too since the 2026-09-03 ruling — see **On `insert`** below.
 interface WriteObservabilityOptions {
   onFieldsDropped?: (event: DroppedFieldsEvent) => void;
   onValidationAdvisory?: (event: ValidationAdvisoryEvent) => void;
+  onMentionsWithheld?: (userIds: readonly string[]) => void;
   strictReadonlyWrites?: boolean;  // refuse instead of stripping. Default: false
 }
 
@@ -454,6 +457,24 @@ The DataProtocol's `createData`, `updateData` and `cloneData` pass this listener
 and answer the hits as `warnings` (`ValidateDataIssue` entries carrying `rule`
 and `severity`), present only when there is at least one hit.
 
+#### `onMentionsWithheld` — who a comment's @mentions will not reach
+
+A `sys_comment` write notifies each user it @mentions, but only a user who can
+read the comment and its record: the mention recipient gate withholds the rest.
+This listener is told the ids of the users the gate withheld on the write the
+options were passed to, whatever its reason: ids only, never the reason. The engine never calls it.
+It reaches the mention writer the way every member of this bag reaches an
+`after*` hook, on `ctx.input.options`, and the writer calls it once per written
+comment that withheld anyone. On an `update`, only a mention the update added is
+judged; a mention the comment already carried was judged when it was written. A
+nested write that a hook or a flow makes inside this one carries its own options,
+so its verdicts never reach this listener.
+
+The DataProtocol's `createData` and `updateData` pass this listener and answer the
+ids as `withheldMentions`, on the requester's own answer to that request only and present only when at
+least one user was withheld. Nothing is stored on the comment: a stored member
+would tell every reader of the comment who cannot read its thread.
+
 <Callout type="warn">
 **Layering — this is the engine seam, and since the 2026-09-03 ruling the only
 one.** The DataProtocol create faces (`createData`, `cloneData`, `createManyData`,
@@ -465,7 +486,7 @@ declares one; none carries a `readonly` policy of its own any more — see
 
 <Callout type="warn">
 `WriteObservabilityOptions` is a **TS-contract-level, in-process-only** bag —
-all three members. It is deliberately not part of the serializable Zod options schemas:
+all four members. It is deliberately not part of the serializable Zod options schemas:
 a function is unrepresentable in JSON Schema and cannot be serialized, so remote
 callers (REST, the client SDK) never receive these events; and putting
 `strictReadonlyWrites` in the serializable bag would let any client toggle
 
@@ -556,6 +556,7 @@ A write-path strip event: caller-supplied fields legally dropped from the payloa
 | **record** | `Record<string, any>` | ✅ | The created record, including server-generated fields (created_at, owner). |
 | **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key' \| 'computed' \| 'stored_expression'> }[]` | optional | Write-observability: caller-supplied fields that were LEGALLY stripped before the record was written — a non-system create cannot seed a static `readonly` column (the strip runs inside `engine.insert`, after the `beforeInsert` hooks, `isSystem`-gated), so those keys are dropped and the field re-derives its default. Present ONLY when ≥1 field was dropped; the create still succeeded without them (status/success semantics unchanged). REST additionally surfaces this as the `X-ObjectStack-Dropped-Fields` response header. Optional — omit-when-empty keeps the shape backward-compatible for existing clients. |
 | **warnings** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | The advisory validation-rule hits of THIS write: each `severity: 'warning'` or `'info'` rule whose verdict on the written record was "violated", with its `rule` name, `severity`, `field`, `code` and author-written `message` — the same element the validate-only preview reports in a row's `warnings`. Advisory rules never block, so the write succeeded; this is the advisory to show the person who made it. Present ONLY when at least one advisory rule hit; a write with no hit omits the key. Hits of a nested write a hook or a flow made inside this one are not included, and a rule that could not be evaluated is not a hit. |
+| **withheldMentions** | `string[]` | optional | The ids of the users this write @mentioned whose mention notification was WITHHELD by the mention recipient gate, so they will not be notified: the gate's own verdict on THIS write, ids only, never the reason. Only a `sys_comment` write fills it, and only on the requester's own answer to the request that made the write; on an update, only a mention the update added is judged. The comment was saved with every mention; the requester is told here that the named users will not be notified. Response-only: never stored on the comment (a stored member would tell every reader who cannot read the thread). Present ONLY when at least one mention was withheld; otherwise the key is omitted. |
 
 ### Nested Shape: `CreateDataResponse.droppedFields[number]`
 
@@ -3041,6 +3042,7 @@ Uninstall package response
 | **record** | `Record<string, any>` | ✅ | Updated record |
 | **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key' \| 'computed' \| 'stored_expression'> }[]` | optional | Write-observability: caller-supplied fields the engine LEGALLY stripped from the write before persisting — static `readonly` or a TRUE `readonlyWhen` predicate. Present ONLY when ≥1 field was dropped; the update still succeeded without them (status/success semantics unchanged — stripping is legitimate, not an error). REST additionally surfaces this as the `X-ObjectStack-Dropped-Fields` response header. Optional — omit-when-empty keeps the shape backward-compatible for existing clients that only read `record`. |
 | **warnings** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | The advisory validation-rule hits of THIS write: each `severity: 'warning'` or `'info'` rule whose verdict on the written record was "violated", with its `rule` name, `severity`, `field`, `code` and author-written `message` — the same element the validate-only preview reports in a row's `warnings`. Advisory rules never block, so the write succeeded; this is the advisory to show the person who made it. Present ONLY when at least one advisory rule hit; a write with no hit omits the key. Hits of a nested write a hook or a flow made inside this one are not included, and a rule that could not be evaluated is not a hit. |
+| **withheldMentions** | `string[]` | optional | The ids of the users this write @mentioned whose mention notification was WITHHELD by the mention recipient gate, so they will not be notified: the gate's own verdict on THIS write, ids only, never the reason. Only a `sys_comment` write fills it, and only on the requester's own answer to the request that made the write; on an update, only a mention the update added is judged. The comment was saved with every mention; the requester is told here that the named users will not be notified. Response-only: never stored on the comment (a stored member would tell every reader who cannot read the thread). Present ONLY when at least one mention was withheld; otherwise the key is omitted. |
 
 ### Nested Shape: `UpdateDataResponse.droppedFields[number]`
 
 
@@ -490,6 +490,14 @@ export interface CreateDataResult<T = any> {
    * person who made it. Present only when at least one rule hit.
    */
   warnings?: ValidateDataIssue[];
+  /**
+   * [#27703] The ids of the users this write @mentioned whose mention
+   * notification the mention gate withheld: they will not be notified. Ids only,
+   * never the reason. Only a `sys_comment` write fills it, only on the answer to
+   * the request that made the write, and nothing about it is stored on the
+   * comment. Present only when at least one mention was withheld.
+   */
+  withheldMentions?: string[];
 }
 
 /**
@@ -544,6 +552,14 @@ export interface UpdateDataResult<T = any> {
    * person who made it. Present only when at least one rule hit.
    */
   warnings?: ValidateDataIssue[];
+  /**
+   * [#27703] The ids of the users this write @mentioned whose mention
+   * notification the mention gate withheld: they will not be notified. Ids only,
+   * never the reason. Only a `sys_comment` write fills it, only on the answer to
+   * the request that made the write, and nothing about it is stored on the
+   * comment. Present only when at least one mention was withheld.
+   */
+  withheldMentions?: string[];
 }
 
 /**
 
@@ -13736,9 +13736,17 @@ export class ObjectStackProtocolImplementation implements
         // — the engine reports them through the write's own options, so a
         // nested write a hook makes inside this one never adds to them.
         const warnings: ValidationAdvisoryEvent[] = [];
+        // [#27703] The mentioned users the mention recipient gate withheld on
+        // THIS write, answered as `withheldMentions` to this request alone: the
+        // mention writer reads the listener off its `after*` hook's
+        // `ctx.input.options`, which is this bag, so neither a nested write
+        // nor any other request's answer ever carries them, and nothing is
+        // stored on the comment.
+        const withheldMentions = new Set<string>();
         const opts: any = {
             onFieldsDropped: (e: DroppedFieldsEvent) => { dropped.push(e); },
             onValidationAdvisory: (e: ValidationAdvisoryEvent) => { warnings.push(e); },
+            onMentionsWithheld: (ids: readonly string[]) => { for (const id of ids) withheldMentions.add(id); },
         };
         if (request.context !== undefined) opts.context = request.context;
         const result = await this.engine.insert(request.object, request.data, opts);
@@ -13756,6 +13764,7 @@ export class ObjectStackProtocolImplementation implements
             record: result,
             ...(dropped.length > 0 ? { droppedFields: dropped } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
+            ...(withheldMentions.size > 0 ? { withheldMentions: [...withheldMentions] } : {}),
         };
     }
 
@@ -13904,6 +13913,10 @@ export class ObjectStackProtocolImplementation implements
         // (see `createData`).
         const warnings: ValidationAdvisoryEvent[] = [];
         opts.onValidationAdvisory = (e: ValidationAdvisoryEvent) => { warnings.push(e); };
+        // [#27703] The mentions this update ADDED that the gate withheld,
+        // answered as `withheldMentions` (see `createData`).
+        const withheldMentions = new Set<string>();
+        opts.onMentionsWithheld = (ids: readonly string[]) => { for (const id of ids) withheldMentions.add(id); };
         // [#6479] At THIS ingress the row is the one the caller named — `request.id`,
         // the path `:id` — and nothing in the payload gets to move it.
         //
@@ -13980,6 +13993,7 @@ export class ObjectStackProtocolImplementation implements
             record: result,
             ...(dropped.length > 0 ? { droppedFields: dropped } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
+            ...(withheldMentions.size > 0 ? { withheldMentions: [...withheldMentions] } : {}),
         };
     }
 
 
@@ -196,6 +196,10 @@ describe('unknown engine option keys are rejected (#4371 option 2)', () => {
         await engine.update('task', { title: 'A4' }, { where: { id: a.id }, onValidationAdvisory: () => {} } as any);
     });
 
+    it('onMentionsWithheld passes on update (contract-declared write observability, #27703)', async () => {
+        await engine.update('task', { title: 'A5' }, { where: { id: a.id }, onMentionsWithheld: () => {} } as any);
+    });
+
     it('searchFields passes on find (read by the $search expansion)', async () => {
         // Legality pin only — the $or/$contains expansion itself is covered by
         // the search-filter tests; this mock driver does not evaluate it.
@@ -259,7 +263,9 @@ describe('unknown engine option keys are rejected (#4371 option 2)', () => {
         // this list must. Spelling it here is what keeps the engine from
         // rejecting a key the TS contract declares. [#22726]
         // `onValidationAdvisory` is the third such member.
-        expectSetMatches('update', EngineUpdateOptionsSchema as any, ['onFieldsDropped', 'onValidationAdvisory', 'strictReadonlyWrites', ...PASSTHROUGH]);
+        // `onMentionsWithheld` (#27703) is the fourth: the engine only carries
+        // it to the `after*` hooks, on `ctx.input.options`.
+        expectSetMatches('update', EngineUpdateOptionsSchema as any, ['onFieldsDropped', 'onValidationAdvisory', 'onMentionsWithheld', 'strictReadonlyWrites', ...PASSTHROUGH]);
         expectSetMatches('delete', EngineDeleteOptionsSchema as any, PASSTHROUGH);
         expectSetMatches('count', EngineCountOptionsSchema as any, []);
         expectSetMatches('aggregate', EngineAggregateOptionsSchema as any, []);
 
@@ -716,7 +716,7 @@ const ENGINE_FIND_OPTION_KEYS: ReadonlySet<string> = new Set([
   ...ENGINE_DRIVER_PASSTHROUGH_KEYS,
 ]);
 const ENGINE_UPDATE_OPTION_KEYS: ReadonlySet<string> = new Set([
-  'context', 'where', 'multi', 'returning', 'onFieldsDropped', 'onValidationAdvisory', 'strictReadonlyWrites',
+  'context', 'where', 'multi', 'returning', 'onFieldsDropped', 'onValidationAdvisory', 'onMentionsWithheld', 'strictReadonlyWrites',
   ...ENGINE_DRIVER_PASSTHROUGH_KEYS,
 ]);
 const ENGINE_DELETE_OPTION_KEYS: ReadonlySet<string> = new Set([