refactor(client): replace the per-field settings preference controller with a namespace settings scope

bindSettingsScope mirrors the Host-side settings owner seam in the browser:
one scope per namespace publishes a snapshot store (status, section value,
revision, writability, host/memory mode), validates sections against the
namespace's serialized wire schema via dsh-client-schema-form, and keeps the
controller's listener-before-read, revisioned serialized writes, latest-wins
publication, conflict recovery, and disposal quiescence. Theme, locale, and
busy-Enter services now take the scope as a constructor collaborator, which
removes the bindPersistence/syncPreference two-phase callback pair and the
defaulted no-op persist writers; hand-written wire guards fall away in favor
of the registered schema. test-runtime gains a stubSettingsScope double.

packages/client/ui-conversation/src/client/apply.ts

@@ -1,7 +1,7 @@
 /** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import { resolveSlotLabel, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import { bindSettingsPreference, type ISessions, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSettingsScope, type ISessions, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
@@ -38,9 +38,7 @@ import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
 import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
-import {
-  BUSY_ENTER_FIELD, CONVERSATION_SETTINGS_NAMESPACE, isBusyEnterBehavior,
-} from '../submission-settings.ts'
+import { CONVERSATION_SETTINGS_NAMESPACE, type ConversationSettings } from '../submission-settings.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -106,14 +104,9 @@ export function apply(ctx: Context): void {
 
   // Apply-time construction keeps store identity bound to this fiber.
   const chatStore = createChatStore()
-  const submissionPolicy = new ComposerSubmissionPolicy()
-  const preference = bindSettingsPreference(ctx, {
-    namespace: CONVERSATION_SETTINGS_NAMESPACE,
-    field: BUSY_ENTER_FIELD,
-    decode: value => isBusyEnterBehavior(value) ? value : undefined,
-    sync: (behavior) => { submissionPolicy.syncPreference(behavior) },
-  })
-  submissionPolicy.bindPersistence((behavior) => { void preference.persist(behavior) })
+  const submissionPolicy = new ComposerSubmissionPolicy(
+    bindSettingsScope<ConversationSettings>(ctx, { namespace: CONVERSATION_SETTINGS_NAMESPACE }),
+  )
 
   ctx.slots.inject('settings.general.item', () => ctx.slots.register({
     name: 'settings.general.item',

packages/client/ui-conversation/src/client/input/submission-policy.ts

@@ -3,35 +3,39 @@
  * preference and resolves keyboard gestures into queue/steer delivery modes;
  * Host and Agent keep the actual delivery-window authority.
  */
-import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  createSnapshotStore, type SettingsScope, type SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   BusyEnterBehavior, ComposerSubmitGesture, InputSubmitMode,
 } from '../contract/composer-submission.ts'
-import { DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'
+import { BUSY_ENTER_FIELD, DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'
+import type { ConversationSettings } from '../../submission-settings.ts'
 
 export { DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'
 
 /**
- * Persisted policy used by both the composer inject face and its Settings row.
+ * Busy-Enter policy used by both the composer inject face and its Settings row.
  * Direct `steer` is intentionally best-effort: AgentLoop turns a closed-window
  * submission into the next waking Queue item.
  */
 export class ComposerSubmissionPolicy {
   /** Reactive preference source for the Settings row. */
   readonly busyEnter: SnapshotStore<BusyEnterBehavior> = createSnapshotStore(DEFAULT_BUSY_ENTER_BEHAVIOR)
-  private persist: (behavior: BusyEnterBehavior) => void
-
-  /** @param persist - durable write callback for explicit behavior changes. */
-  constructor(persist: (behavior: BusyEnterBehavior) => void = () => {}) {
-    this.persist = persist
-  }
+  private readonly host: SettingsScope<ConversationSettings> | undefined
 
   /**
-   * Bind the owning plugin's durable writer before the policy is exposed.
-   * @param persist - callback accepting explicit behavior changes.
+   * @param host - durable preference scope owned by the providing plugin;
+   * absent compositions stay process-local. The adoption subscription shares
+   * the scope's plugin lifetime — a disposed scope never publishes again, so
+   * the policy needs no release hook.
    */
-  bindPersistence(persist: (behavior: BusyEnterBehavior) => void): void {
-    this.persist = persist
+  constructor(host?: SettingsScope<ConversationSettings>) {
+    this.host = host
+    if (host !== undefined) {
+      host.subscribe(() => { this.adopt(host) })
+      this.adopt(host)
+    }
   }
 
   /**
@@ -53,21 +57,23 @@ export class ComposerSubmissionPolicy {
   }
 
   /**
-   * Change the plain-Enter behavior used during busy state.
+   * Change the plain-Enter behavior used during busy state; the live value
+   * publishes before the durable write starts.
    * @param behavior - Queue or Steer.
    */
   setBusyEnter(behavior: BusyEnterBehavior): void {
     if (this.busyEnter.getSnapshot() === behavior) return
     this.busyEnter.set(behavior)
-    this.persist(behavior)
+    void this.host?.set(BUSY_ENTER_FIELD, behavior)
   }
 
   /**
-   * Apply a Host preference without writing it back.
-   * @param behavior - validated behavior from settings.
+   * Adopt the scope's accepted durable behavior without writing it back.
+   * @param host - the constructor-narrowed scope driving this adoption.
    */
-  syncPreference(behavior: BusyEnterBehavior): void {
-    if (this.busyEnter.getSnapshot() === behavior) return
-    this.busyEnter.set(behavior)
+  private adopt(host: SettingsScope<ConversationSettings>): void {
+    const section = host.getSnapshot().value
+    if (section === undefined || this.busyEnter.getSnapshot() === section.busyEnter) return
+    this.busyEnter.set(section.busyEnter)
   }
 }

packages/client/ui-conversation/src/index.ts

@@ -5,19 +5,16 @@ import z from 'schemastery'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import {
   BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONVERSATION_SETTINGS_NAMESPACE,
-  DEFAULT_BUSY_ENTER_BEHAVIOR, type BusyEnterBehavior,
+  DEFAULT_BUSY_ENTER_BEHAVIOR, type ConversationSettings,
 } from './submission-settings.ts'
 
 export {
   BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONVERSATION_SETTINGS_NAMESPACE,
-  DEFAULT_BUSY_ENTER_BEHAVIOR, type BusyEnterBehavior,
+  DEFAULT_BUSY_ENTER_BEHAVIOR, type BusyEnterBehavior, type ConversationSettings,
 } from './submission-settings.ts'
 
-interface ConversationSettings {
-  busyEnter: BusyEnterBehavior
-}
-
-const ConversationSettingsSchema: z<ConversationSettings> = z.object({
+/** Durable conversation schema; also the wire envelope the browser scope validates against. */
+export const ConversationSettingsSchema: z<ConversationSettings> = z.object({
   [BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR),
 })
 

packages/client/ui-conversation/src/submission-settings.ts

@@ -15,11 +15,8 @@ export type BusyEnterBehavior = typeof BUSY_ENTER_BEHAVIORS[number]
 /** Default preserves Enter-as-Queue for running conversations. */
 export const DEFAULT_BUSY_ENTER_BEHAVIOR: BusyEnterBehavior = 'queue'
 
-/**
- * Narrow one settings-wire value to a busy-Enter behavior.
- * @param value - value crossing the settings boundary.
- * @returns whether the value names a supported behavior.
- */
-export function isBusyEnterBehavior(value: unknown): value is BusyEnterBehavior {
-  return BUSY_ENTER_BEHAVIORS.some(behavior => behavior === value)
+/** Durable conversation section shared by the Host schema and the browser scope. */
+export interface ConversationSettings {
+  /** Delivery mode for plain Enter while the addressed agent is busy. */
+  busyEnter: BusyEnterBehavior
 }

packages/client/ui-conversation/tests/host.spec.ts

@@ -4,7 +4,6 @@ import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-a
 import {
   CONVERSATION_SETTINGS_NAMESPACE, DEFAULT_BUSY_ENTER_BEHAVIOR, apply,
 } from '@deepseek-ai/dsh-client-ui-conversation'
-import { isBusyEnterBehavior } from '../src/submission-settings.ts'
 
 class MemorySettings extends Settings {
   readonly writable = true
@@ -15,12 +14,6 @@ class MemorySettings extends Settings {
 }
 
 describe('ui-conversation host', () => {
-  it('narrows settings-wire values to the supported behavior pair', () => {
-    expect(isBusyEnterBehavior('queue')).toBe(true)
-    expect(isBusyEnterBehavior('steer')).toBe(true)
-    expect(isBusyEnterBehavior('later')).toBe(false)
-  })
-
   it('registers, validates, and disposes the durable busy-Enter preference', async () => {
     const ctx = new Context()
     await ctx.plugin(MemorySettings).await()

packages/client/ui-conversation/tests/submission-policy.spec.ts

@@ -1,8 +1,10 @@
 // @vitest-environment jsdom
 import { describe, expect, it, vi } from 'vitest'
+import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import {
   ComposerSubmissionPolicy, DEFAULT_BUSY_ENTER_BEHAVIOR,
 } from '../src/client/input/submission-policy.ts'
+import type { ConversationSettings } from '../src/submission-settings.ts'
 
 describe('ComposerSubmissionPolicy', () => {
   it('defaults to Queue and only applies the preference while running', () => {
@@ -16,8 +18,6 @@ describe('ComposerSubmissionPolicy', () => {
     expect(policy.resolve(true, 'accelerated', false)).toBe('queue')
 
     const changed = vi.fn()
-    const persist = vi.fn()
-    policy.bindPersistence(persist)
     policy.busyEnter.subscribe(changed)
     policy.setBusyEnter('steer')
     expect(changed).toHaveBeenCalledTimes(1)
@@ -25,25 +25,42 @@ describe('ComposerSubmissionPolicy', () => {
     expect(policy.resolve(true, 'accelerated', true)).toBe('queue')
     expect(policy.resolve(false, 'enter', true)).toBe('queue')
     expect(policy.resolve(false, 'accelerated', true)).toBe('queue')
-    expect(persist).toHaveBeenCalledWith('steer')
   })
 
-  it('syncs a Host preference without writing it back and leaves an identical write untouched', () => {
-    const persist = vi.fn()
-    const policy = new ComposerSubmissionPolicy(persist)
-    policy.syncPreference('steer')
+  it('writes an explicit change through the scope after publishing it locally', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    const observed: string[] = []
+    let liveBehavior = (): string => 'unconstructed'
+    const scope: typeof host.scope = {
+      ...host.scope,
+      set: (field, value) => {
+        observed.push(`${field}=${String(value)}:${liveBehavior()}`)
+        return host.scope.set(field, value)
+      },
+    }
+    const policy = new ComposerSubmissionPolicy(scope)
+    liveBehavior = () => policy.busyEnter.getSnapshot()
+    policy.setBusyEnter('steer')
+    expect(observed).toEqual(['busyEnter=steer:steer'])
+    expect(host.set).toHaveBeenCalledWith('busyEnter', 'steer')
+    expect(host.set).toHaveBeenCalledOnce()
+  })
+
+  it('adopts a Host preference without writing it back and leaves an identical write untouched', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    const policy = new ComposerSubmissionPolicy(host.scope)
+    host.publish({ status: 'ready', value: { busyEnter: 'steer' }, revision: 1, writable: true })
     expect(policy.busyEnter.getSnapshot()).toBe('steer')
     policy.setBusyEnter('steer')
-    expect(persist).not.toHaveBeenCalled()
+    expect(host.set).not.toHaveBeenCalled()
+    host.publish({ value: { busyEnter: 'steer' }, revision: 2 })
+    expect(policy.busyEnter.getSnapshot()).toBe('steer')
   })
 
-  it('publishes the in-memory preference before calling the durable writer', () => {
-    const policy = new ComposerSubmissionPolicy()
-    const persist = vi.fn(() => {
-      expect(policy.busyEnter.getSnapshot()).toBe('steer')
-    })
-    policy.bindPersistence(persist)
-    policy.setBusyEnter('steer')
-    expect(persist).toHaveBeenCalledOnce()
+  it('adopts a section already standing at construction', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    host.publish({ status: 'ready', value: { busyEnter: 'steer' }, revision: 1, writable: true })
+    const policy = new ComposerSubmissionPolicy(host.scope)
+    expect(policy.busyEnter.getSnapshot()).toBe('steer')
   })
 })