docs(spec): keep the ruling id out of the customer-facing droppedFields string

`check:doc-authoring` refuses an internal issue id inside customer-facing spec
text, and the rewritten `.describe()` had put one there: a `.describe()` string
projects into `content/docs/references/**` and the generated skill artifacts,
whose readers have no tracker to resolve `#NNNN` against.

The id moves to an adjacent `//` comment — the placement the gate itself
prescribes for a reference that is load-bearing for an internal reader — and the
customer-facing sentence now states the mechanism directly instead of citing the
ruling that produced it, which is what a caller reading the field can act on.

Claude-Session: https://claude.ai/code/session_016N6xmWt5hYm94ffVEwGH8x
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

content/docs/references/api/protocol.mdx

@@ -569,7 +569,7 @@ A write-path strip event: caller-supplied fields legally dropped from the payloa
 | **object** | `string` | ✅ | Object name |
 | **records** | `Record<string, any>[]` | ✅ | Created records |
 | **count** | `number` | ✅ | Number of records created |
-| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key'> }[]` | optional | Write-observability: caller-supplied `readonly` fields the in-engine create-side strip (`engine.insert`, `isSystem`-gated) removed before the rows were written. AGGREGATED across the batch (one event per object/reason with the UNION of dropped field names) rather than per-row, because this response is `{ object, records, count }` and has no per-row slot to hang a drop set on — a union is the only view it can represent. So read a name here as "at least one row dropped this field", NOT "every row dropped the same set": since ruling C (#14147) the strip runs INSIDE `engine.insert` after the `beforeInsert` hooks and exempts keys a hook itself wrote, tracked per row, so rows a hook stamped differently drop different sets. Present ONLY when ≥1 field was dropped; the creates still succeeded without them (count/success unchanged). Optional — omit-when-empty keeps the shape backward-compatible. (The per-row `insertMany`/`batch` paths carry per-row `droppedFields` on each result instead — see BatchOperationResultSchema.) |
+| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key'> }[]` | optional | Write-observability: caller-supplied `readonly` fields the in-engine create-side strip (`engine.insert`, `isSystem`-gated) removed before the rows were written. AGGREGATED across the batch (one event per object/reason with the UNION of dropped field names) rather than per-row, because this response is `{ object, records, count }` and has no per-row slot to hang a drop set on — a union is the only view it can represent. So read a name here as "at least one row dropped this field", NOT "every row dropped the same set": the strip runs INSIDE `engine.insert` after the `beforeInsert` hooks and exempts keys a hook itself wrote, tracked per row: rows where a hook stamped a protected key drop a different set from rows where it did not. Present ONLY when ≥1 field was dropped; the creates still succeeded without them (count/success unchanged). Optional — omit-when-empty keeps the shape backward-compatible. (The per-row `insertMany`/`batch` paths carry per-row `droppedFields` on each result instead — see BatchOperationResultSchema.) |
 
 ### Nested Shape: `CreateManyDataResponse.droppedFields[number]`
 

packages/spec/src/api/protocol.zod.ts

@@ -2354,16 +2354,20 @@ export const CreateManyDataResponseSchema = lazySchema(() => z.object({
   object: z.string().describe('Object name'),
   records: z.array(z.record(z.string(), z.unknown())).describe('Created records'),
   count: z.number().describe('Number of records created'),
+  // The per-row read below is maintainer ruling C (#14147): the static-`readonly` strip
+  // moved into `engine.insert`, after `beforeInsert`, exempting keys a hook wrote
+  // (`rowHookWrittenKeys`). The id stays in this comment, never in the `.describe()` —
+  // that string is printed AT the customer, who has no tracker to resolve it.
   droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
     'Write-observability: caller-supplied `readonly` fields the in-engine create-side ' +
     'strip (`engine.insert`, `isSystem`-gated) removed before the rows were written. AGGREGATED across the batch ' +
     '(one event per object/reason with the UNION of dropped field names) rather than per-row, ' +
     'because this response is `{ object, records, count }` and has no per-row slot to hang a ' +
     'drop set on — a union is the only view it can represent. So read a name here as "at least ' +
-    'one row dropped this field", NOT "every row dropped the same set": since ruling C (#14147) ' +
-    'the strip runs INSIDE `engine.insert` after the `beforeInsert` hooks and exempts keys a ' +
-    'hook itself wrote, tracked per row, so rows a hook stamped differently drop different ' +
-    'sets. Present ONLY when ≥1 field was dropped; the creates still succeeded ' +
+    'one row dropped this field", NOT "every row dropped the same set": the strip runs INSIDE ' +
+    '`engine.insert` after the `beforeInsert` hooks and exempts keys a hook itself wrote, ' +
+    'tracked per row: rows where a hook stamped a protected key drop a different set from ' +
+    'rows where it did not. Present ONLY when ≥1 field was dropped; the creates still succeeded ' +
     'without them (count/success unchanged). Optional — omit-when-empty keeps the shape ' +
     'backward-compatible. (The per-row `insertMany`/`batch` paths carry per-row `droppedFields` ' +
     'on each result instead — see BatchOperationResultSchema.)'