@@ -0,0 +1,16 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+feat(plugin-auth): a sign-in that skips the OIDC seams can apply the IdP locale rule through `AuthManager.applyIdpLocaleClaim`
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+An external OIDC sign-in already sets the user's language preference (`sys_user.locale`) from the IdP's `locale` claim. A host whose own door signs a user in without passing through better-auth's OIDC seams, such as the cloud's sso-exchange hand-off, had no way to apply the same rule, because the package entry exported none of it. Now it can, through the running auth manager (`ctx.getService('auth')`):
+
+- **`AuthManager.applyIdpLocaleClaim(userId, claim)`** applies a claim (`{ providerId?, value }`) under the same rule and the same `idp-locale:` record as the OIDC path: the column is written only while it is unset or still holds the value an IdP sign-in last wrote, so a language the user chose in the environment is kept. The claim is closed against the i18n service's locales, and an unsupported one clears only an IdP-written value. It never throws: a failure is reported at `warn` and the user keeps the preference they had.
+- **`IdpLocaleClaim`** is exported as a type from the package entry.
+- **One owner for the rule.** The OIDC JIT path now settles its staged claim through the same method, so its behaviour is unchanged.
+
+Nothing to do for existing hosts.
@@ -28,7 +28,7 @@ import {
 import {
   type LinkingAuthContext,
 } from './implicit-account-linking.js';
-import { IdpLocaleSync } from './idp-locale-claim.js';
+import { IdpLocaleSync, type IdpLocaleClaim } from './idp-locale-claim.js';
 import type { IDataEngine } from '@objectstack/core';
 import {
   API_KEY_DEFAULT_EXPIRY_DAYS,
@@ -2169,6 +2169,21 @@ export class AuthManager {
     warn: (message, meta) => this.config.logger?.warn?.(message, meta),
   });
 
+  /**
+   * Apply an IdP's `locale` claim to a user, for a sign-in that does not run
+   * through the OIDC seams (a host's own session hand-off): the user's
+   * language preference (`sys_user.locale`) is written only while it is unset
+   * or still holds the value an IdP sign-in last wrote, so a language the user
+   * chose in the environment is kept. The same call the OIDC JIT path makes,
+   * with the same `idp-locale:` record; the claim is closed against the i18n
+   * service's locales, and an unsupported one clears only an IdP-written
+   * value. Never throws: a failure is reported at `warn` and the user keeps
+   * the preference they had. The rule and its record: `idp-locale-claim.ts`.
+   */
+  public applyIdpLocaleClaim(userId: string, claim: IdpLocaleClaim): Promise<void> {
+    return this.idpLocale.apply(userId, claim);
+  }
+
   /**
    * [ADR-0093 D7] The users created in each in-flight better-auth request,
    * keyed by that request's endpoint context — the object better-auth hands
 
@@ -3,7 +3,7 @@
 // The IdP's `locale` claim → `sys_user.locale` — see `idp-locale-claim.ts`
 // for the rule this file pins.
 //
-// Two layers:
+// Three layers:
 //
 //  1. PURE — reading the claim off a `validateUserInfo` source, closing it
 //     against the supported locales, and the write decision.
@@ -12,10 +12,16 @@
 //     `/callback/:id`) through the platform IdP, a generic-OAuth provider
 //     whose token and userinfo endpoints are stubbed. The assertions read
 //     what landed: the `sys_user.locale` column and the IdP record beside it.
+//  3. The PACKAGE ENTRY — `AuthManager.applyIdpLocaleClaim`, the call a host
+//     whose sign-in skips the OIDC seams makes (the cloud's sso-exchange
+//     hand-off), imported from `./index` and run over the same engine; and
+//     the pin that it and the OIDC settle step are one method.
 
 import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
 import { assertEngineDeleteDispatch, assertEngineUpdateDispatch, assertEngineFindOnePredicate } from '@objectstack/objectql';
 import { AuthManager } from './auth-manager';
+// The package entry, as a host outside the package imports it.
+import * as entry from './index';
 import { PLATFORM_IDP_PROVIDER_ID } from './implicit-account-linking';
 import {
   IdpLocaleSync,
@@ -436,3 +442,118 @@ describe('a JIT sign-in through the platform IdP sets the user language preferen
     expect(warn.mock.calls.filter(([m]) => String(m).includes('no i18n service reports a supported locale'))).toHaveLength(1);
   });
 });
+
+describe('the OIDC JIT path and the entry call apply the rule through one method', () => {
+  it('a sign-in through the platform IdP settles its claim through IdpLocaleSync.apply', async () => {
+    const apply = vi.spyOn(IdpLocaleSync.prototype, 'apply');
+    try {
+      const engine = createMemoryEngine();
+      idpProfile = { locale: 'zh-CN' };
+
+      await signInWithIdp(makeManager(engine));
+
+      expect(apply).toHaveBeenCalledTimes(1);
+      expect(apply).toHaveBeenCalledWith(
+        userRow(engine).id,
+        { providerId: PLATFORM_IDP_PROVIDER_ID, value: 'zh-CN' },
+        expect.anything(),
+      );
+      expect(userRow(engine).locale).toBe('zh-CN');
+    } finally {
+      apply.mockRestore();
+    }
+  });
+});
+
+describe('the package entry applies the rule for a sign-in that skips the OIDC seams', () => {
+  const USER_ID = 'usr_entry_1';
+  const CLOUD = 'objectos-cloud';
+
+  /** A user the host's own hand-off already holds: created, never signed in through OIDC. */
+  const seedUser = async (engine: ReturnType<typeof createMemoryEngine>) => {
+    await engine.insert('sys_user', { id: USER_ID, email: EMAIL, name: 'Synthetic Person' });
+  };
+  const entryManager = (engine: unknown, config: Record<string, unknown> = {}) =>
+    new entry.AuthManager({
+      secret: SECRET,
+      baseUrl: BASE,
+      dataEngine: engine,
+      getI18n: () => ({ getLocales: () => SUPPORTED }),
+      ...config,
+    } as any);
+  const claim = (value: unknown): entry.IdpLocaleClaim => ({ providerId: CLOUD, value });
+  const userOf = (engine: ReturnType<typeof createMemoryEngine>) =>
+    (engine.tables.get('sys_user') ?? []).find((u: any) => u.id === USER_ID);
+  const verificationRows = (engine: ReturnType<typeof createMemoryEngine>) =>
+    JSON.stringify(engine.tables.get('sys_verification') ?? []);
+
+  it('⭐ unset: the claim is written, with the idp-locale record beside it', async () => {
+    const engine = createMemoryEngine();
+    await seedUser(engine);
+    const manager = entryManager(engine);
+
+    await expect(manager.applyIdpLocaleClaim(USER_ID, claim('zh-CN'))).resolves.toBeUndefined();
+
+    expect(userOf(engine).locale).toBe('zh-CN');
+    expect(recordOf(engine, USER_ID)).toBe('zh-CN');
+  });
+
+  it('⭐ still the recorded value: a later claim overwrites it, record and column alike', async () => {
+    const engine = createMemoryEngine();
+    await seedUser(engine);
+    const manager = entryManager(engine);
+    await manager.applyIdpLocaleClaim(USER_ID, claim('zh-CN'));
+
+    await manager.applyIdpLocaleClaim(USER_ID, claim('en-US'));
+
+    expect(userOf(engine).locale).toBe('en');
+    expect(recordOf(engine, USER_ID)).toBe('en');
+  });
+
+  it('⭐ a local choice: kept, and neither the column nor the record is written', async () => {
+    const engine = createMemoryEngine();
+    await seedUser(engine);
+    const manager = entryManager(engine);
+    await manager.applyIdpLocaleClaim(USER_ID, claim('zh-CN'));
+    userOf(engine).locale = 'ja-JP';
+    const update = vi.spyOn(engine, 'update');
+    const recordsBefore = verificationRows(engine);
+
+    await manager.applyIdpLocaleClaim(USER_ID, claim('en'));
+
+    expect(userOf(engine).locale).toBe('ja-JP');
+    expect(update).not.toHaveBeenCalled();
+    expect(verificationRows(engine)).toBe(recordsBefore);
+  });
+
+  it('runs through the same IdpLocaleSync.apply the OIDC settle step calls', async () => {
+    const apply = vi.spyOn(IdpLocaleSync.prototype, 'apply');
+    try {
+      const engine = createMemoryEngine();
+      await seedUser(engine);
+
+      await entryManager(engine).applyIdpLocaleClaim(USER_ID, claim('zh-CN'));
+
+      expect(apply).toHaveBeenCalledTimes(1);
+      expect(apply).toHaveBeenCalledWith(USER_ID, claim('zh-CN'));
+    } finally {
+      apply.mockRestore();
+    }
+  });
+
+  it('never throws: a user store that refuses the write is reported at warn', async () => {
+    const engine = createMemoryEngine();
+    await seedUser(engine);
+    const warn = vi.fn();
+    const manager = entryManager(engine, { logger: { warn, info: () => {}, error: () => {}, debug: () => {} } });
+    engine.failUpdates.add('sys_user');
+
+    await expect(manager.applyIdpLocaleClaim(USER_ID, claim('zh-CN'))).resolves.toBeUndefined();
+    await expect(manager.applyIdpLocaleClaim('', claim('zh-CN'))).resolves.toBeUndefined();
+    await expect(manager.applyIdpLocaleClaim(USER_ID, undefined as never)).resolves.toBeUndefined();
+
+    expect(userOf(engine).locale ?? null).toBeNull();
+    expect(recordOf(engine, USER_ID)).toBeUndefined();
+    expect(warn.mock.calls.filter(([m]) => String(m).includes('IdP locale claim was not applied'))).toHaveLength(1);
+  });
+});
@@ -57,6 +57,11 @@
  * A sign-in that is refused mints no session, and the staged claim dies with
  * its request.
  *
+ * A sign-in that never passes through those seams (a host's own session
+ * hand-off, such as the cloud's) applies the same rule through
+ * `AuthManager.applyIdpLocaleClaim`, which calls {@link IdpLocaleSync.apply}:
+ * the very method the settle step calls, so the rule has one owner.
+ *
  * A failure here never fails a sign-in. It is a functional degradation — the
  * user sees the deployment default instead of the IdP's language, visibly —
  * so it is reported at `warn`.
@@ -91,7 +96,12 @@ export function idpLocaleRecordIdentifier(userId: string): string {
   return `${IDP_LOCALE_RECORD_PREFIX}:${userId}`;
 }
 
-/** What one IdP sign-in asserted about the user's language. */
+/**
+ * What one IdP sign-in asserted about the user's language. Applying it
+ * ({@link IdpLocaleSync.apply}, published as `AuthManager.applyIdpLocaleClaim`)
+ * writes `sys_user.locale` only while it is unset or still the value an IdP
+ * sign-in last wrote, so a local choice is kept; applying it never throws.
+ */
 export interface IdpLocaleClaim {
   /** The provider that asserted it, for the record and the logs. */
   providerId?: string;
@@ -195,6 +205,22 @@ export class IdpLocaleSync {
     this.staged.delete(ctx);
     const userId = (session as { userId?: unknown } | null)?.userId;
     if (typeof userId !== 'string' || !userId) return;
+    await this.apply(userId, claim, ctx);
+  }
+
+  /**
+   * Apply one IdP sign-in's locale claim to a user, under the rule in the
+   * module header: `sys_user.locale` is written while it is unset or still
+   * holds the value the IdP path last wrote, and a local choice is kept. The
+   * `idp-locale:` record beside it is written in the same step. The OIDC JIT
+   * path reaches it through {@link settle}; a sign-in that never runs through
+   * better-auth's OIDC seams calls it with the claim it holds. `ctx` is the
+   * better-auth endpoint context when there is one; without it the auth store
+   * is resolved off the auth instance. Never throws: a failure is reported at
+   * `warn` and the user keeps the language preference they had.
+   */
+  async apply(userId: string, claim: IdpLocaleClaim, ctx?: unknown): Promise<void> {
+    if (typeof userId !== 'string' || !userId || !claim) return;
     try {
       const supported = this.deps.getSupportedLocales();
       if (!supported || supported.length === 0) {
 
@@ -33,6 +33,13 @@ export {
   authEmailLocaleFromRequest,
   AuthManager,
 } from './auth-manager.js';
+// The IdP locale rule, for a host whose sign-in does not run through the OIDC
+// seams (the cloud's sso-exchange hand-off): `AuthManager.applyIdpLocaleClaim`
+// takes this claim. A user's language preference is written only while it is
+// unset or still the value an IdP sign-in last wrote, so a local choice is
+// kept; the call never throws. The pure steps of the rule stay unexported, so
+// the rule keeps one owner.
+export type { IdpLocaleClaim } from './idp-locale-claim.js';
 export * from './ensure-default-organization.js';
 // [ADR-0131 D3 / D10 fate 3] The Default Organization's boot invariant, for the
 // v18 organization-ownership ceremony (`os migrate organization-ownership