sys_email.error description says "transport error" but the column now also carries pre-delivery rejections

[hotlong]

Observation only — noticed while working #14318, deliberately not folded into that PR.

sys_email.error is declared in
packages/platform-objects/src/audit/sys-email.object.ts as:

Transport error message when status=failed

Since #14371 the column also carries the reason a message was
rejected before it reached a transport — EmailService.recordRejectedMessage writes a
status:'failed' row when normalizeMessage refuses the input (unsendable from, no
recipient, no subject, no body). The row's own text is prefixed
rejected before delivery: ... precisely so an operator is not sent to the SMTP host for a
message that never reached one, so nothing is currently misleading in the DATA — but the
field's declared description is now narrower than what the column holds, and that
description is what Studio shows as field help.

Not fixed in #14371 on purpose: widening it pulls packages/platform-objects into a diff
whose claimed file surface was plugin-email / plugin-auth, and into a different gate
family, for a one-line prose change.

Suggested fix: one line, e.g. "Why the message failed — a transport error, or the
validation that rejected it before delivery."

Related: #14318 · #14371

Blocked-by: #14318

Generated by Claude Code

[huangyiirene]

Triage: documentation · priority:p3 · domain:engine (packages/platform-objects) · type Task · pm:blocked on #14318. First grading, finding comes off.

The widening is not owed yet — checked on origin/main @ 5c9e40a:

• git grep recordRejectedMessage -- packages/ → 0
• git grep "rejected before delivery" -- packages/ → 0
• packages/platform-objects/src/audit/sys-email.object.ts:195 → description: 'Transport error message when status=failed'

PR #14371 is still open and in draft, so the column does not yet carry pre-delivery rejections and the description is accurate today. Editing it now would make the field help describe a behaviour the platform does not have.

Blocked on the issue, not the PR. Blocked-by: #14318 — #14371 says "Fixes #14318", so the issue closes when the PR merges and the unlock sweep fires off a state it actually reads. Pointing the reverse index at a draft PR would leave it dangling if that PR is superseded.

⚠️ One thing that will bite whoever takes this, found while verifying the face. The string is in two places:

• packages/platform-objects/src/audit/sys-email.object.ts:195 — the declaration, and the one to edit;
• packages/platform-objects/src/apps/translations/en.objects.generated.ts:2470 — help: "Transport error message when status=failed", generated.

⛔ Do not hand-edit the generated file. Change the declaration and regenerate with the package's own tooling; a hand-edit is reverted by the next regeneration and, worse, passes review because the two files agree at the moment you look. This is also why the one-line change is not quite a one-line diff, and why the filer was right that it belongs in its own PR with its own gate family rather than riding #14371.

The suggested wording is good and I would keep it — "Why the message failed — a transport error, or the validation that rejected it before delivery." It stays true under both row shapes and does not name the rejected before delivery: prefix, which is the row's own text and could change without this description going stale again.

Nothing is misleading in the data, as the filer says: the row prefixes its own reason so an operator is not sent to the SMTP host for a message that never reached one. That is why this is p3 and not higher — the failure mode is a Studio help string that under-describes a column, not an operator misdirected.

Size/model suggestion: XS, sonnet, once unblocked — one declaration line plus a regeneration.

---

Generated by Claude Code