docs(platform-objects): widen sys_email.error description to cover pre-delivery rejections

[zhuangjianguo]

Fixes #14372

What

sys_email.error (packages/platform-objects/src/audit/sys-email.object.ts) was declared as:

Transport error message when status=failed

Since #14371, EmailService.recordRejectedMessage (plugin-email/src/email-service.ts:677/:852) also writes status: 'failed' rows for messages normalizeMessage rejects before they reach a transport (unsendable from, no recipient, no subject, no body), prefixed rejected before delivery: (:875). The declared field description was narrower than what the column now holds.

Widened to the wording settled in triage (issue comment 5504375428, reconfirmed in 5536386432/5537220287):

Why the message failed — a transport error, or the validation that rejected it before delivery.

How

Edited only the declaration (sys-email.object.ts:195) and regenerated the platform-objects i18n bundle with its own tooling — node scripts/check-i18n-bundles.mjs --write — rather than hand-editing en.objects.generated.ts (its help: key at line 2479, per the source-of-truth guardrail in this repo's docs). Confirmed the generated help: string actually changed and that check:i18n re-verifies clean afterward.

The translated locales (zh-CN/ja-JP/es-ES) keep their existing (now-stale relative to the new English) human translations by the extractor's own merge-mode design — that is expected behaviour for this bundle (untouched keys are not drift) and outside this card's scope.

No behaviour change: no schema key added/removed, recordRejectedMessage untouched, no column change.

Net change: exactly 3 files, +25/-2 (matches GitHub's own changed_files/additions/deletions on this PR as of HEAD 71590c470) — .changeset/sys-email-error-description-widen.md, packages/platform-objects/src/apps/translations/en.objects.generated.ts, packages/platform-objects/src/audit/sys-email.object.ts. The commit list carries extra entries from a merge-base hiccup fixed mid-review (see note at the bottom) — those are not part of this PR's actual diff.

Verification

• git grep positive controls on origin/main @ 97bcd99e: recordRejectedMessage (email-service.ts:677,:852) and "rejected before delivery: " (:875) both fire — premise re-confirmed live (was 0 on 2026-09-02, non-zero now).
• pnpm --filter @objectstack/platform-objects test — 33/33 files, 518/518 tests pass.
• pnpm --filter @objectstack/platform-objects typecheck — clean.
• pnpm check:i18n (full, 9 packages) — green; filtered re-run — platform-objects in sync (11 bundles).
• pnpm check:i18n-stale-fill — green (this is the gate that would have caught a stranded stale leaf on a revised source string; 0 stale-fill leaves).
• No other package/bundle in the repo carries the old string (git grep clean).

Local gate families (per family, re-derived with node scripts/pm/dispatch-gates.mjs, no path args, on the corrected 3-file surface — merge base 460134af8 — at HEAD 71590c470)

37/37 green:

gate	exit
node scripts/check-adr-0087-registration.mjs --self-test	0
node scripts/check-changeset-no-major.mjs --self-test	0
node scripts/check-ci-filter-parity.mjs	0
node scripts/check-closing-keyword-parity.mjs	0
node scripts/check-closing-keyword-parity.mjs --self-test	0
node scripts/check-comment-mask-adoption.mjs	0
node scripts/check-comment-mask-adoption.mjs --self-test	0
node scripts/check-comment-mask-corpus.mjs	0
node scripts/check-empty-changeset.mjs --self-test	0
node scripts/check-keyed-text-bounds.mjs	0
node scripts/check-keyed-text-bounds.mjs --self-test	0
node scripts/check-plugin-teardown-shape.mjs	0
node scripts/check-plugin-teardown-shape.mjs --self-test	0
node scripts/check-system-context-census.mjs	0
node scripts/check-system-context-census.mjs --self-test	0
node scripts/check-undeclared-dep-imports.mjs	0
node scripts/check-undeclared-dep-imports.mjs --self-test	0
node scripts/docs-audit/check-affected-docs.mjs	0
node scripts/docs-audit/check-drift-comment.mjs	0
node scripts/pm/release-rehearsal-clone.mjs --self-test	0
pnpm check:changeset-gate-self-tests	0
pnpm check:cross-package-test-inputs	0
pnpm check:doc-authoring	0
pnpm check:dual-build-cjs-loads	0
pnpm check:i18n	0
pnpm check:i18n-stale-fill	0
pnpm check:logger-receiver-detach	0
pnpm check:nul-bytes	0
pnpm check:objectui-changeset	0
pnpm check:page-declaration-shape	0
pnpm check:pm-half-states	0
pnpm check:published-files	0
pnpm check:refd-timer-probe	0
pnpm check:slot-lookup	0
pnpm check:test-source-alias	0
pnpm check:type-source-resolution	0
pnpm check:watch-hint-literal	0

(29 matched by path + 2 by change kind [check:i18n, check:i18n-stale-fill, since this diff revises an existing source string] + 6 declared whole-tree.) pnpm check:dual-build-cjs-loads needs a full pnpm build first (it refuses with exit 3 and states nothing was measured otherwise) — done before this run.

Changeset

@objectstack/platform-objects ships this description as field metadata (Studio reads it as the field's help text), so this is not comment-only — added a patch changeset.

Note: merge-base correction mid-review

An earlier push in this PR's history briefly desynced its merge-base from origin/main (a git filter-branch used to clean up commit-message trailers rewrote commits that had been merged in from origin/main, replacing them with content-identical-but-different-SHA copies — so git merge-base origin/main HEAD stopped advancing past this branch's original fork point, and GitHub's three-dot diff/file-count briefly over-reported). Fixed by merging the current origin/main in again (no rebase, no force-push) — git merge-base origin/main HEAD now correctly resolves to origin/main's real tip, and the three-dot and two-dot diffs agree on exactly the 3 files above. The gate results in this body were re-derived and re-run fresh after that fix, superseding an earlier report-comment reading on the issue that (harmlessly, since content never changed) predates it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/platform-objects, touching 2 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/environment-variables.mdx (via sys_email (symbol, a field of const object enObjects))
• content/docs/kernel/runtime-services/sms-service.mdx (via sys_email (symbol, a field of const object enObjects))
• content/docs/plugins/packages.mdx (via sys_email (symbol, a field of const object enObjects))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via sys_email (symbol, a field of const object enObjects))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 2 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 460134af85f7ab2cf68abc62f1bbb9783b8899dd → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c1e84067765fbc5ab4e1fbadd460b173dbd08b20 — the merge of head 71590c4709a91ceada04ce9f8f929b7e32e002be into base 460134af85f7ab2cf68abc62f1bbb9783b8899dd, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c1e84067765fbc5ab4e1fbadd460b173dbd08b20 && git checkout c1e84067765fbc5ab4e1fbadd460b173dbd08b20
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 460134af85f7ab2cf68abc62f1bbb9783b8899dd 71590c4709a91ceada04ce9f8f929b7e32e002be && git checkout -B drift-repro 460134af85f7ab2cf68abc62f1bbb9783b8899dd && git merge --no-ff 71590c4709a91ceada04ce9f8f929b7e32e002be

node scripts/docs-audit/affected-docs.mjs --json 460134af85f7ab2cf68abc62f1bbb9783b8899dd

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 460134af85f7ab2cf68abc62f1bbb9783b8899dd → pass the list as
args.docs, on the commit named under Which tree this was computed on.