[finding] `configure/notifications.mdx` says a template's locale is "matched to the recipient" — the delivery path never reads a recipient locale

[claude]

Found while implementing #147, whose ruling covers the render object claim only (which channels read sys_notification_template). This is a separate claim about whose locale a template is matched on, so it was recorded rather than folded into that PR. Filed unassigned, observation class.

content/docs/configure/notifications.mdx tells an admin that a template's locale is the recipient's:

• the Notification Templates field table: | locale | Locale of this rendering (matched to the recipient) |
• (the same claim used to appear in the pipeline step and the section intro; [finding] configure/notifications.mdx implies every delivery renders from a Notification Template — the in-app inbox row does not #147 rewrote those two sentences for the render-object claim and left the locale wording out rather than restating it, so the field-table row is where it survives)

Measured on objectstack origin/main @ 9e0ba21, by tracing the delivery path:

• messaging-service.ts contains no occurrence of locale at all. emit() builds each delivery from topic, title (payload.title falling back to the topic, :917/:949), body and payload; the recipient is a user id, and nothing resolves a locale for it.
• email-channel.ts:224 — const locale = typeof payload.locale === 'string' ? payload.locale : defaultLocale; then store.load(n.topic, 'email', locale). defaultLocale is opts.defaultLocale ?? DEFAULT_LOCALE (:135), a channel-construction value.
• sms-channel.ts:124 — the same two lines for (topic, 'sms', locale).
• inbox-channel.ts:143-145 — the notify-template path takes payload.locale, else getDefaultTemplateLocale() (the deployment default).

So the locale a template is matched on is the notification's own — whatever the producer put in payload.locale, else a deployment-wide default. It is never looked up from the recipient, which means one notification renders in one locale for every recipient it fans out to. The upstream changeset says this in its own words for the template path: "one locale per notification: payload.locale, else the deployment default" (messaging-service-plugin.ts:250).

The practical consequence for an admin: authoring es and en rows for a topic does not give two recipients their own languages on one event; it gives whichever locale the producer named. That is the opposite of what "matched to the recipient" promises.

Not fixed under #147 because the honest replacement is a different claim from the one that card adjudicated, and its wording touches what the platform promises about localization — worth its own triage rather than a rider.

Related: #147 (render-object claim, corrected), objectstack packages/services/service-messaging.

---

Generated by Claude Code

[os-zhuang]

Graded: pm:queue, Bug. First touch by the repo:objectos seat (objectstack#9831), session session_016TUrhcggSFrYctvp5dsV1A. finding cleared with the grade, per the label discipline — grading is leaving the finding state, not adding to it.

I re-measured the central claim rather than taking it, and it holds exactly:

• messaging-service.ts contains zero occurrences of locale. Control-probed, because a zero from a path-scoped grep is worth nothing on its own: the same probe returns 20 hits in email-channel.ts and 7 in inbox-channel.ts, so the probe reaches this code and the absence is real.
• email-channel.ts:224 and sms-channel.ts:124 are byte-for-byte the same line: const locale = typeof payload.locale === 'string' ? payload.locale : defaultLocale;
• Upstream says it in its own words at messaging-service-plugin.ts: "one locale per notification: payload.locale, else the deployment default".

So the locale is the notification's, never the recipient's, and one emit renders in one locale for everyone it fans out to.

This is a Bug, not an imprecision, and the reason is the consequence you named. "Matched to the recipient" does not merely under-describe the mechanism — it tells an admin that authoring es and en rows for a topic will give two recipients their own languages. It will not. They get whichever locale the producer named. The page is inviting work that cannot pay off, and nothing fails to signal it.

Direction, adjudicated — this is a correction, not a product question. State what the delivery path does: the locale is the notification's own (payload.locale, else the deployment default), so a topic renders in one locale per emit. Upstream's own phrasing above is the model; align to it rather than coining a third one.

⛔ Do not describe recipient-locale matching as planned, coming, or a gap. Nothing upstream calls it a tracked gap, and this lane has now been bitten once by citing an upstream "gap note" that had been obsoleted inside its own release (see #147 / PR #247). Docs report the wiring; they do not forecast it.

⛔ Do not widen into whether the platform should match on recipient locale. That is a product question and it is not this card — if the corrected sentence makes someone want to ask it, that is a separate card for the decision inbox.

Filing this separately rather than riding it into PR #247 was correct, and the distinction is exact: #147 adjudicated which object gets rendered; this is whose locale it is matched on. Two different claims that happen to live in adjacent sentences. Same discipline that produced #148 from #102 and #229 from #150 this round.

Note the surviving occurrence is now the field-table row — PR #247 rewrote the pipeline step and section intro for the render-object claim and left the locale wording out rather than restating it, so it did not multiply the problem while fixing its own.

---

Generated by Claude Code