feat(settings,plugin-email): state the live mail transport on Setup → Email - #25448

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-email, @objectstack/service-settings, touching 18 documentable anchor(s).

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

• content/docs/data-modeling/drivers.mdx (via SettingsService (symbol, a top-level class))
• content/docs/kernel/runtime-services/sms-service.mdx (via isConfigured (symbol, a method of interface LiveMailTransportSource))
• content/docs/protocol/kernel/config-resolution.mdx (via SettingsService (symbol, a top-level class), registerSettingsRoutes (symbol, a top-level function))
• content/docs/protocol/kernel/index.mdx (via SettingsService (symbol, a top-level class))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 4863eec2ce048a95edb21bbd3d44f088d4f2acd8 && git checkout 4863eec2ce048a95edb21bbd3d44f088d4f2acd8
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d0a1361bdabc153b2fb927b8f7ef6f024ecc6891 39af42e75abdfef4f6be187cc0836925fa2d253c && git checkout -B drift-repro d0a1361bdabc153b2fb927b8f7ef6f024ecc6891 && git merge --no-ff 39af42e75abdfef4f6be187cc0836925fa2d253c

node scripts/docs-audit/affected-docs.mjs --json d0a1361bdabc153b2fb927b8f7ef6f024ecc6891

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 d0a1361bdabc153b2fb927b8f7ef6f024ecc6891 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 39af42e75abdfef4f6be187cc0836925fa2d253c
Local-runs: none

The face is the declaration face. This review is owed only by the Clause-②: yes (widening: …) line: no published schema or governed path is in the tree (check-governed-merges --pr 25448: 0 hits), and the PR declares no narrowing. Rendered by the lane seat as its review of record.

① Derived judgments

1. The new public surface of @objectstack/service-settings — right, and additive only. The new members are SettingsService.registerLiveStatus(namespace, provider) and liveStatusOf(namespace, ctx). The types SettingsLiveStatus and SettingsLiveStatusProvider and the constant SETTINGS_LIVE_STATUS_BANNER_ID = 'live_status' are exported from index.ts. No existing member changes its signature. getNamespace() and the registered manifest are untouched, so in-process readers see exactly what they saw before.
2. The GET /api/settings/:namespace payload — a widening, right. When a provider is registered, one info_banner heads manifest.specifiers. liveStatusOf runs after getNamespace has already passed the namespace's read gate, so the statement reaches no caller the values did not already reach. The banner shape (type, id, label, required: false, bannerText, bannerSeverity) is one the spec's info_banner already accepts, and the new pin parses it under SettingsNamespacePayloadSchema. Without a provider the payload is unchanged. No write path is touched, so no input is newly refused.
3. The throwing provider — right. It becomes an error-severity "Live status unavailable" banner plus one warn. The cause text goes to the log, not to the page.
4. plugin-email's statement — right. The branch is EmailService.isConfigured(), read at call time; the transport class only names the transport. The provider awaits Promise.allSettled over in-flight re-applies, so it cannot reject, and it only waits on work already started. Registration goes through the structural MailSettingsSurface behind a typeof … === 'function' guard, so a host whose settings service predates the method keeps booting. registerLiveStatus throws on an unknown namespace, the same rule registerAction already applies one call later. The built-in mail manifest is always registered.
5. Interaction with plugin-email: saving mail provider "None (log only — no real delivery)" keeps the previous SMTP transport, so mail is still delivered while the page and the log say it is not #25450, noted rather than judged. plugin-email: saving mail provider "None (log only — no real delivery)" keeps the previous SMTP transport, so mail is still delivered while the page and the log say it is not #25450 is the defect where saving provider log keeps the SMTP transport. Under it, the banner says mail is delivered through SMTP, which is what the live transport actually does. The statement is therefore truthful about the defect, not masking it. plugin-email: saving mail provider "None (log only — no real delivery)" keeps the previous SMTP transport, so mail is still delivered while the page and the log say it is not #25450 fixes the transport and is dispatched after this PR lands.

② Semver level

patch on both packages, with Clause-②: yes (widening: …) and Metadata-protocol: none in both the changeset and the PR body. The PR-body line was corrected through the relay. The re-run Check Changeset on this head is green (14:27Z). AGENTS.md: a non-protocol change, widening or breaking, ships patch. Nothing a metadata author can write changes: info_banner already exists, and the reserved id is placed by the route, not authored. So none is right.

③ Boundary flags

• The reserved id is stated, not enforced. SETTINGS_LIVE_STATUS_BANNER_ID is documented as "a manifest must not declare it". No manifest on main declares live_status (git grep), so there is no collision today. Enforcement at registerNamespace would be a later hardening, not a defect of this PR.
• No translation for the banner. This is declared in the PR's acceptance notes, and the reason is sound: the console's id-keyed banner lookup would overwrite computed text.
• Console half. After Save, @object-ui/console SettingsView merges only the PUT values and never refetches the manifest. The banner therefore updates on the next page read, not in place. This is declared with a Seam: line and left on the card (Part of #25335), which stays open for the ui lane.
• SMS. service-sms can adopt the same registerLiveStatus from ISmsService.isConfigured(). That is not part of this card.
• Ablation leg 1 crashed with a ReferenceError instead of exercising the mutation. The dev reported it as not counted and replaced it with legs 2 to 4, each of which reds the pin it targets.
• Check-runs on this head: 48 check-runs, 39 success and 9 skipped by design, none failed.

Implemented-by: claude/issue-25335-email-transport-statement
Reviewed-by: session_016g7nYP9wdNx1GDa5XDr7Uy

VERDICT: PASS

席位核对 · ACCEPT · 2026-10-23T14:38Z

domain:services seat 1 (seat post #6021) · os-sales · session_016g7nYP9wdNx1GDa5XDr7Uy · card #25335, server half (S, in-seat subagent; os-dev-report and the Clause-② addendum 6367155487 on the card) · reviewed head 39af42e75a

• Review of record: the TIER_DEFAULT record above on this head, declaration face, PASS.
• Diff: 12 files, +469 / −2.
  • service-settings gains registerLiveStatus / liveStatusOf. The GET /api/settings/:namespace route puts the provider's statement first in manifest.specifiers, as an info_banner with id live_status. getNamespace() and the registered manifest are unchanged.
  • plugin-email registers the mail statement from isConfigured(), waiting first for any re-apply still running.
  • Three route-test fakes gained liveStatusOf.
  • There are two new pin files, 5 + 6 cases.
• Pins (report):
  • plugin-email: 37 files / 676 tests pass.
  • service-settings: 60 files / 995 tests pass. Both typechecks exit 0.
  • Ablations 2–4 each red their target pin, and every restore is clean. Leg 1 crashed (ReferenceError), and the dev reported it as not counted.
  • Gates at the final head: 70 derived, 70 run, 0 not measured.
• Clause-② correction: the seat ruled the arm yes (widening: …) because new exports ship. The changeset commit (39af42e75a) carries it. The PR-body line was changed through the relay (issue_patch, read back identical). Check Changeset re-ran on the edited body and is green.
• CI on this head: 48 check-runs, 39 success and 9 expected skips, none failed. git merge-tree onto today's main is clean.
• Body: the seat added the attribution header and requested the os-sales reviewer, through the relay. The closing footer is present.
• Commit trailers: model-free Co-authored-by: Claude + Claude-Session.
• Landing: not governed (check-governed-merges --pr 25448: 471 lines). Ready + auto-merge through the relay. Part of #25335, so the card stays open for the console half: after Save, SettingsView never re-reads the manifest. The Seam: line is in the PR body, and the seat routes it to the ui lane on landing.
• Sequenced after this: plugin-email: saving mail provider "None (log only — no real delivery)" keeps the previous SMTP transport, so mail is still delivered while the page and the log say it is not #25450 (saving provider log keeps SMTP delivering) shares email-plugin.ts and is dispatched once this and plugin-email: the Send test email refusals tell the admin to pass "to" in the request body — name the page's control instead (same family as #25345) #25424 land. Until then, the new banner honestly says SMTP is live in that state.

Generated by Claude Code