refactor(service-settings): the display language travels beside the settings context, not in it

Claude-Session: https://claude.ai/code/session_01Utp6CYUAEJV7QpzuJm62Te
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/services/service-settings/src/index.ts

@@ -41,6 +41,7 @@ export {
   type SettingsWritePredicate,
   type SettingsWritePredicateInput,
   type SettingsWriteRefusal,
+  type SettingsDisplayOptions,
   SETTINGS_LIVE_STATUS_BANNER_ID,
   type SettingsAuditSink,
   type SettingsContext,

packages/services/service-settings/src/localization-currency-lock.test.ts

@@ -235,7 +235,7 @@ describe('the copy — every locale the settings bundle ships', () => {
     await svc.set('localization', 'currency', 'USD', ctx);
     objects.push(INVOICE);
     rates.push({ organization_id: ORG, currency: 'EUR' }, { organization_id: ORG, currency: 'JPY' });
-    const err = await refusalOf(svc.set('localization', 'currency', 'EUR', { ...ctx, locale }));
+    const err = await refusalOf(svc.setMany('localization', { currency: 'EUR' }, ctx, { locale }));
     expect(err.fields[0].message.startsWith(opening)).toBe(true);
   });
 });

packages/services/service-settings/src/localization-currency-lock.ts

@@ -233,11 +233,11 @@ function usageConstraint(usage: CurrencyUsage): Record<string, unknown> {
  * refused while the currency is used. Setting it while unset passes.
  */
 export function localizationCurrencyWritePredicate(engine: CurrencyUsageEngine): SettingsWritePredicate {
-  return async ({ current, organizationId, ctx }) => {
+  return async ({ current, organizationId, locale }) => {
     if (isUnset(current)) return undefined;
     const usage = await readCurrencyUsage(engine, organizationId ?? null);
     if (!isUsed(usage)) return undefined;
-    const copy = currencyLockCopy(ctx.locale);
+    const copy = currencyLockCopy(locale);
     return {
       message: copy.refusal(String(current), describeCurrencyUsage(copy, usage)),
       constraint: usageConstraint(usage),
@@ -257,12 +257,12 @@ export function localizationCurrencyLiveStatus(
   engine: CurrencyUsageEngine,
   currentCurrency: (ctx: Parameters<SettingsLiveStatusProvider>[0]['ctx']) => Promise<unknown>,
 ): SettingsLiveStatusProvider {
-  return async ({ ctx, organizationId }): Promise<SettingsLiveStatus | undefined> => {
+  return async ({ ctx, organizationId, locale }): Promise<SettingsLiveStatus | undefined> => {
     const organization = await organizationId();
     if (organization === undefined) return undefined;
     const usage = await readCurrencyUsage(engine, organization);
     if (!isUsed(usage)) return undefined;
-    const copy = currencyLockCopy(ctx.locale);
+    const copy = currencyLockCopy(locale);
     const described = describeCurrencyUsage(copy, usage);
     const current = await currentCurrency(ctx);
     if (isUnset(current)) {

packages/services/service-settings/src/settings-routes.ts

@@ -205,7 +205,8 @@ function refuseHeldSession(res: IHttpResponse, ctx: SettingsContext | undefined)
  * The caller's display language, read the way REST's metadata door reads it:
  * the top `Accept-Language` tag, else `?locale`. It only picks the language of
  * prose a write predicate or a live-status provider composes
- * (`SettingsContext.locale`); it authorizes nothing.
+ * (`SettingsDisplayOptions`); it authorizes nothing, and it never enters the
+ * caller's context.
  */
 function requestLocaleOf(req: IHttpRequest): string | undefined {
   const header = req.headers?.['accept-language'] ?? req.headers?.['Accept-Language'];
@@ -295,7 +296,7 @@ export function registerSettingsRoutes(
       // `getNamespace`, which in-process consumers call to read values: the
       // mail plugin reads `getNamespace('mail')` while rebuilding the very
       // transport its statement waits on.
-      const liveStatus = await service.liveStatusOf(ns, { ...ctx, locale: requestLocaleOf(req) });
+      const liveStatus = await service.liveStatusOf(ns, ctx, { locale: requestLocaleOf(req) });
       const manifest = liveStatus
         ? { ...payload.manifest, specifiers: [liveStatus, ...payload.manifest.specifiers] }
         : payload.manifest;
@@ -353,8 +354,9 @@ export function registerSettingsRoutes(
       const result = await service.setMany(
         ns,
         dropEchoedSecretMasks(body, secretKeys),
+        ctx,
         // The language a write predicate's refusal is written in.
-        { ...ctx, locale: requestLocaleOf(req) },
+        { locale: requestLocaleOf(req) },
       );
       // The write response carries resolved values too — including cascade
       // entries the caller never submitted (an upper-scope secret it may not

packages/services/service-settings/src/settings-service.ts

@@ -23,6 +23,7 @@ import {
   type SettingsLiveStatus,
   type SettingsLiveStatusProvider,
   type SettingsWritePredicate,
+  type SettingsDisplayOptions,
   SETTINGS_LIVE_STATUS_BANNER_ID,
   type SettingsAuditSink,
   type SettingsContext,
@@ -1619,6 +1620,7 @@ export class SettingsService {
   async liveStatusOf(
     namespace: string,
     ctx: SettingsContext = {},
+    display: SettingsDisplayOptions = {},
   ): Promise<SettingsManifest['specifiers'][number] | undefined> {
     const provider = this.liveStatusProviders.get(namespace);
     if (!provider) return undefined;
@@ -1628,6 +1630,7 @@ export class SettingsService {
         namespace,
         ctx,
         organizationId: async () => organizationReachRowOwner(await this.organizationReachOf(ctx)),
+        locale: display.locale,
       });
     } catch (err: any) {
       this.logger?.warn?.(
@@ -2277,11 +2280,15 @@ export class SettingsService {
    * naming each such key (`invalid_value`, `constraint: { scope: 'user' }`):
    * the row it would store names no owner, and the user rung answers only its
    * owner, so no reader would ever see it while the write reported success.
+   *
+   * `display` picks the language of a write predicate's refusal, and nothing
+   * else (see {@link refuseByWritePredicates}).
    */
   async setMany(
     namespace: string,
     patch: Record<string, unknown>,
     ctx: SettingsContext = {},
+    display: SettingsDisplayOptions = {},
   ): Promise<Record<string, ResolvedSettingValue>> {
     // The pre-bind window: refuse rather than resolve against a store nothing
     // will ever read. See `assertEngineBound`.
@@ -2365,7 +2372,7 @@ export class SettingsService {
     // may refuse a change the declarations above accept. After them, so a
     // malformed value is told about its own fault first; before the crypto
     // pass and every write, so a refused batch writes nothing.
-    await this.refuseByWritePredicates(reg, namespace, patch, ctx, reach);
+    await this.refuseByWritePredicates(reg, namespace, patch, ctx, reach, display);
 
     // #8026 — a declared-encrypted key with nothing able to encrypt it fails
     // the WHOLE batch, here, rather than part-way down the write loop below.
@@ -2579,6 +2586,7 @@ export class SettingsService {
     patch: Record<string, unknown>,
     ctx: SettingsContext,
     reach: OrganizationReach | undefined,
+    display: SettingsDisplayOptions,
   ): Promise<void> {
     const byKey = this.writePredicates.get(namespace);
     if (!byKey) return;
@@ -2591,7 +2599,7 @@ export class SettingsService {
       if (stableStringify(next) === stableStringify(current)) continue;
       const scope = reg.scopes.get(key)!;
       const organizationId = scope === 'global' || !reach ? undefined : organizationReachRowOwner(reach) ?? null;
-      const refusal = await predicate({ namespace, key, next, current, organizationId, ctx });
+      const refusal = await predicate({ namespace, key, next, current, organizationId, ctx, locale: display.locale });
       if (!refusal) continue;
       const spec = ((reg.manifest.specifiers ?? []) as Array<Record<string, unknown>>)
         .find((s) => s.key === key);

packages/services/service-settings/src/settings-service.types.ts

@@ -82,12 +82,19 @@ export interface SettingsContext {
    * resolver sets it to have its held sessions refused too.
    */
   authGate?: AuthGate;
+}
+
+/**
+ * How a settings call's computed prose is written — never who calls or what
+ * they may do, which is {@link SettingsContext}'s alone.
+ */
+export interface SettingsDisplayOptions {
   /**
    * The caller's display language (BCP-47), for prose a
    * {@link SettingsWritePredicate} refusal or a {@link SettingsLiveStatusProvider}
-   * statement composes. The settings routes set it from the request
-   * (`Accept-Language`, else `?locale`). Never an authorization input and never
-   * read by the resolver; absent, such prose is written in English.
+   * statement composes. The settings routes pass it from the request
+   * (`Accept-Language`, else `?locale`). Absent, such prose is written in
+   * English.
    */
   locale?: string;
 }
@@ -348,11 +355,13 @@ export interface SettingsWritePredicateInput {
    */
   organizationId: string | null | undefined;
   ctx: SettingsContext;
+  /** The language the refusal is written in — {@link SettingsDisplayOptions.locale}. */
+  locale?: string;
 }
 
 /**
  * A predicate's refusal. `message` is the sentence the caller reads under the
- * field, written in `ctx.locale`; `constraint` carries its discrete values
+ * field, written in the input's `locale`; `constraint` carries its discrete values
  * (`FieldError.constraint`, ADR-0114), so a client can compose its own text.
  */
 export interface SettingsWriteRefusal {
@@ -412,7 +421,9 @@ export type SettingsLiveStatusProvider = (input: {
    * Resolved only when called.
    */
   organizationId: () => Promise<string | null | undefined>;
-}) =>Promise<SettingsLiveStatus | undefined> | SettingsLiveStatus | undefined;
+  /** The language the statement is written in — {@link SettingsDisplayOptions.locale}. */
+  locale?: string;
+}) => Promise<SettingsLiveStatus | undefined> | SettingsLiveStatus | undefined;
 
 /**
  * The `info_banner` id that carries a namespace's live status. Reserved: a

packages/services/service-settings/src/settings-write-predicate.test.ts

@@ -69,7 +69,7 @@ describe('SettingsService write predicate', () => {
     const { svc, spy } = rig(({ current }) => (current ? { message: 'Locked.' } : undefined));
     await svc.set('localization', 'currency', 'USD', ctx);
     await expect(svc.set('localization', 'currency', null, ctx)).rejects.toBeInstanceOf(SettingsValidationError);
-    expect(spy.mock.calls.at(-1)![0]).toMatchObject({ current: 'USD', next: null });
+    expect(spy.mock.calls[spy.mock.calls.length - 1][0]).toMatchObject({ current: 'USD', next: null });
     expect((await svc.get('localization', 'currency', ctx)).value).toBe('USD');
   });