docs(plugin-approvals): correct what the approval snapshot column is FOR (#11837)

`sys_approval_request`'s module docstring justified `payload_json` with "used
by notifications so they can render before the record is locked or changed".
That consumer does not exist. Measured against every `this.notify(...)` call
site in `approval-service.ts` -- all 12 -- each passes `{ title, message,
actionUrl }` (two also `actions`), built from `object_name` / `record_id` and
the caller's comment. None reads `payload_json` or the parsed `payload`.

The sentence was the only documented justification for the column holding a
FULL row, and it was cited as such during the #10749 consumer inventory before
anyone checked it. The docstring now states the real reason: the snapshot is
retained as audit evidence of what was actually submitted (so the column stays
whole at rest) and is served redacted per reader by the subject object's
field-level read controls via `getReadableFields`, on the approvals-inbox door
and the generic data door alike (#11039).

The field's own `description` is deliberately unchanged -- it is accurate, and
it, not the JSDoc, is the string extracted into the four generated i18n
bundles. Proven rather than assumed: regenerating with the documented command
left all four bundles byte-identical, and a positive control (mutating the
extracted `description`) moved the `en` leaf, so the zero is a real zero.

Also carries the residual documentation #10749's closure assigned to the next
docs touch in this lane: `payload-redaction.ts` recorded hidden-vs-serialization
as an OPEN `packages/spec` question, and it has since been ruled (maintainer,
2026-08-24). That paragraph now states the ruling -- `hidden: true` stays
UI-only; `internal: true` is the serialization primitive -- and points an
author who needs a field kept out of read results at `internal` (#7728,
ADR-0049) rather than at `hidden`, which never governed serialization.

Documentation only: no runtime behaviour, schema field, or type signature
changes. The corrected JSDoc does ship to consumers in `dist/index.d.ts`,
which is why this carries a patch changeset rather than none.

Part of #11041


Claude-Session: https://claude.ai/code/session_01APWX2AwT3a4xDcjPCe8bk4

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

Author: os-sam

.changeset/approval-snapshot-docstring-audit-evidence.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+Correct what `sys_approval_request.payload_json` is documented to be FOR — it is audit evidence served redacted per reader, not a notification source
+
+The object's module docstring — which ships to consumers in the package's type
+declarations — justified the snapshot column with: *"used by notifications so
+they can render before the record is locked or changed."* That consumer does
+not exist. Measured against every `this.notify(...)` call site in
+`approval-service.ts`, all **12** of them, each passes a payload of
+`{ title, message, actionUrl }` (two also carry `actions`), built from
+`object_name` / `record_id` and the caller's own comment. **None** reads
+`payload_json` or the parsed `payload`.
+
+This is more than tidiness: that sentence was the only documented
+justification for the column holding a *full* row, and it was cited as such
+during the #10749 consumer inventory before anyone checked it. The docstring
+now states the real reason — the snapshot is retained as **audit evidence of
+what was actually submitted**, so the column stays whole at rest, and is served
+**redacted per reader** by the subject object's field-level read controls via
+`getReadableFields`, on the approvals-inbox door and the generic data door
+alike (#11039).
+
+The field's own `description` is deliberately unchanged: `Record snapshot at
+submission time` is accurate, and it — unlike the JSDoc — is the string
+extracted into the four generated i18n bundles, so no translation leaf moves
+and no locale is left holding an English seed.
+
+Also carried in the same pass, the residual documentation the #10749 closure
+assigned to the next docs touch in this lane: `payload-redaction.ts` recorded
+`hidden`-vs-serialization as an **open** `packages/spec` question, and it has
+since been ruled (maintainer, 2026-08-24, applying the 2026-08-12 lineage).
+That paragraph now states the ruling — **`hidden: true` stays UI-only;
+`internal: true` is the serialization primitive** — so an author who needs a
+field kept out of read results is pointed at `internal: true` (#7728,
+ADR-0049) rather than at `hidden`, which never governed serialization.
+
+Documentation only: no runtime behaviour, no schema field, and no public type
+signature changes.

packages/plugins/plugin-approvals/src/payload-redaction.ts

@@ -44,8 +44,22 @@
  *   it. Making it govern serialization here alone would make the approval path
  *   stricter than a direct read of the very same row (so it would close no
  *   leak — the approver can just read the record), while breaking every drawer
- *   that renders a `hidden` business column. That is a `packages/spec`
- *   semantics question, and it is left open rather than decided here.
+ *   that renders a `hidden` business column.
+ *
+ *   That `packages/spec` semantics question was left open here when this seam
+ *   landed. **It has since been ruled** (maintainer, 2026-08-24, applying the
+ *   2026-08-12 lineage rather than making a new rule): **`hidden: true` stays
+ *   UI-only; `internal: true` is the serialization primitive.** `hidden`
+ *   gains no serialization semantic — it says "Hidden from default UI" and
+ *   nothing more. The read-side omission primitive is `internal: true`
+ *   (#7728, ADR-0049): the engine OMITS the key from `find`/`findOne` results,
+ *   the 201 create body and the by-id update body, on the default projection
+ *   AND when a client names the field in `?select=`. `internal` exists
+ *   PRECISELY BECAUSE `hidden` is not that, so an author who needs a field
+ *   kept out of read results declares `internal: true`; declaring `hidden`
+ *   and expecting omission is the mistake this paragraph exists to stop.
+ *   Per-caller field visibility — what this seam applies — remains
+ *   `requiredPermissions` / permission sets / `maskingRule`.
  */
 
 /** The slice of the security service this seam consumes. */

packages/plugins/plugin-approvals/src/sys-approval-request.object.ts

@@ -17,9 +17,16 @@ import { APPROVAL_STATUSES, APPROVAL_STATUS_LABELS } from '@objectstack/spec/con
  * snapshots the Approval node config (approvers / behaviour) the request was
  * opened with.
  *
- * `payload_json` captures a snapshot of the target record at submission
- * time — used by notifications so they can render before the record is
- * locked or changed.
+ * `payload_json` captures a snapshot of the target record at submission time.
+ * It is retained as **audit evidence of what was actually submitted**, so the
+ * column stays whole AT REST; it is served **redacted per reader** — the
+ * SUBJECT object's field-level read controls are applied at serve time from
+ * the security service's `getReadableFields`, on the approvals-inbox door and
+ * on the generic data door alike (#11039).
+ *
+ * ⛔ Notifications are NOT a consumer of this snapshot, and the audit-evidence
+ * sentence above — not "notifications need it" — is why the column holds a
+ * full row. See the note on the field itself.
  *
  * @namespace sys
  */
@@ -214,6 +221,22 @@ export const SysApprovalRequest = ObjectSchema.create({
       group: 'State',
     }),
 
+    // The module docstring above used to justify this column with "used by
+    // notifications so they can render before the record is locked or
+    // changed". That consumer does not exist, and the claim was cited as the
+    // reason the column holds a FULL row before anyone checked it. Measured
+    // against every `this.notify(...)` call site in `approval-service.ts` —
+    // all 12 of them: each passes `{ title, message, actionUrl }` (two also
+    // `actions`), built from `object_name` / `record_id` and the caller's
+    // comment. None reads this column or the parsed `payload`. The real
+    // readers are the serve path (`rowFromRequest` -> `payload`, redacted per
+    // reader), the decide-time approver re-resolution and the org backfill,
+    // both under SYSTEM_CTX, and the free-text predicate.
+    //
+    // The `description` below is deliberately UNCHANGED: it is accurate, and
+    // it is extracted into the four generated i18n bundles as `help`. The
+    // false sentence lived only in the JSDoc above, which is not extracted —
+    // so this correction moves no translation leaf.
     payload_json: Field.textarea({
       label: 'Snapshot',
       required: false,