Clarify read-only settings snapshots and shared transaction plumbing

docs/ARCHITECTURE.md

@@ -40,9 +40,13 @@ MagnifierOverlay
 
 ```text
 SettingsCoordinator.Current
+(read-only snapshot contract)
       ↓
 CreateWorkingCopy
       ↓
+SettingsUseCaseContext
+(shared snapshot/event/commit plumbing)
+      ↓
 Domain-service mutation
       ↓
 SettingsNormalizer.Normalize
@@ -57,13 +61,14 @@ Current.ReplaceWith
 one synchronous Changed event
 ```
 
-A failed mutation or failed write does not replace committed settings and does not publish a settings change. `SettingsCoordinator.Current` returns a defensive snapshot, so consumers cannot mutate the committed in-memory object outside a transaction.
+A failed mutation or failed write does not replace committed settings and does not publish a settings change. `SettingsCoordinator.Current` exposes `IReadOnlySightAdaptSettings` and returns a defensive snapshot. Mutable `SightAdaptSettings` is confined to explicit transaction callbacks and normalization/persistence boundaries. `SettingsUseCaseContext` centralizes snapshot, change-event and commit plumbing for application use-case façades without sharing their domain commands. `Commit` and `PersistCurrent` use one persistence execution path; only `Commit` publishes the synchronous `Changed` event after a successful write.
 
 ## Authorities
 
 | Concern | Authority |
 |---|---|
-| Settings transaction and published snapshots | `SettingsCoordinator` |
+| Settings transaction and published read-only snapshots | `SettingsCoordinator` |
+| Shared use-case snapshot/event/commit plumbing | `SettingsUseCaseContext` |
 | Settings JSON persistence and atomic replacement | `SettingsStore` |
 | Persisted JSON DTOs and legacy-field migration | `PersistedSettingsMapper` |
 | Schema, profile, assignment and reference normalization | explicit `ISettingsNormalizationPass` implementations |

src/SightAdapt/ConfigurationUseCases.cs

@@ -2,31 +2,39 @@ namespace SightAdapt;
 
 internal sealed class ConfigurationUseCases
 {
-    private readonly SettingsCoordinator _settingsCoordinator;
+    private readonly SettingsUseCaseContext _settings;
 
     public ConfigurationUseCases(
         SettingsCoordinator settingsCoordinator)
-    {
-        _settingsCoordinator = settingsCoordinator ??
+        : this(new SettingsUseCaseContext(
+            settingsCoordinator ??
             throw new ArgumentNullException(
-                nameof(settingsCoordinator));
+                nameof(settingsCoordinator))))
+    {
+    }
+
+    internal ConfigurationUseCases(
+        SettingsUseCaseContext settings)
+    {
+        _settings = settings ??
+            throw new ArgumentNullException(nameof(settings));
     }
 
-    public SightAdaptSettings Snapshot =>
-        _settingsCoordinator.Current;
+    public IReadOnlySightAdaptSettings Snapshot =>
+        _settings.Snapshot;
 
     public string SettingsPath =>
-        _settingsCoordinator.SettingsPath;
+        _settings.SettingsPath;
 
     public event EventHandler? Changed
     {
-        add => _settingsCoordinator.Changed += value;
-        remove => _settingsCoordinator.Changed -= value;
+        add => _settings.Changed += value;
+        remove => _settings.Changed -= value;
     }
 
     public SettingsCommitResult SetAutomaticMode(bool enabled)
     {
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             AutomaticModeManagementService.Set(
                 settings,
@@ -41,7 +49,7 @@ public SettingsCommitResult Apply(
         ArgumentException.ThrowIfNullOrWhiteSpace(
             change.ExecutablePath);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             var assignment =
                 ProfileResolver.RequireAssignmentByExecutablePath(
@@ -85,7 +93,7 @@ public SettingsCommitResult<bool> AddOrEnable(
     {
         ArgumentNullException.ThrowIfNull(identity);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             var result =
                 ApplicationAssignmentService.AddOrEnable(
@@ -100,7 +108,7 @@ public SettingsCommitResult Remove(string executablePath)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(executablePath);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
             ApplicationAssignmentService.Remove(
                 settings,
                 ProfileResolver.RequireAssignmentByExecutablePath(
@@ -115,7 +123,7 @@ public SettingsCommitResult UpdateTuning(
         ArgumentException.ThrowIfNullOrWhiteSpace(profileId);
         ArgumentNullException.ThrowIfNull(values);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
             VisualProfileManagementService.UpdateTuning(
                 settings,
                 ProfileResolver.RequireVisualProfile(

src/SightAdapt/RuntimeCoordinator.cs

@@ -12,7 +12,7 @@ internal sealed class RuntimeCoordinator
     private readonly IRuntimeEnvironment _environment;
     private readonly RuntimeOverlayActivator _overlayActivator;
     private readonly AutomaticActivationService _automaticActivation;
-    private readonly Func<SightAdaptSettings> _readSettings;
+    private readonly Func<IReadOnlySightAdaptSettings> _readSettings;
     private bool _committingSettings;
 
     public RuntimeCoordinator(
@@ -43,7 +43,7 @@ internal RuntimeCoordinator(
         ApplicationStateController stateController,
         IRuntimeOverlay overlay,
         IRuntimeEnvironment environment,
-        Func<SightAdaptSettings>? readSettings)
+        Func<IReadOnlySightAdaptSettings>? readSettings)
     {
         _settingsCoordinator = settingsCoordinator ??
             throw new ArgumentNullException(nameof(settingsCoordinator));
@@ -257,7 +257,7 @@ public void DisableForExit()
         _overlayActivator.DisableForExit();
     }
 
-    private SightAdaptSettings ReadSettings()
+    private IReadOnlySightAdaptSettings ReadSettings()
     {
         return _readSettings();
     }

src/SightAdapt/SettingsCoordinator.cs

@@ -65,7 +65,7 @@ public SettingsCoordinator(
         _current = _store.Load();
     }
 
-    public SightAdaptSettings Current =>
+    public IReadOnlySightAdaptSettings Current =>
         _current.CreateWorkingCopy();
 
     public string SettingsPath => _store.SettingsPath;
@@ -98,13 +98,36 @@ public SettingsCommitResult<T> Commit<T>(
         Func<SightAdaptSettings, T> mutation)
     {
         ArgumentNullException.ThrowIfNull(mutation);
+        return ExecuteTransaction(
+            mutation,
+            publishChanged: true);
+    }
+
+    public SettingsCommitResult PersistCurrent()
+    {
+        var result = ExecuteTransaction<object?>(
+            _ => null,
+            publishChanged: false);
+
+        return result.Succeeded
+            ? SettingsCommitResult.Success()
+            : SettingsCommitResult.Failure(
+                result.ErrorMessage ??
+                "Settings could not be saved.");
+    }
+
+    private SettingsCommitResult<T> ExecuteTransaction<T>(
+        Func<SightAdaptSettings, T> operation,
+        bool publishChanged)
+    {
+        ArgumentNullException.ThrowIfNull(operation);
 
         var candidate = _current.CreateWorkingCopy();
         T value;
 
         try
         {
-            value = mutation(candidate);
+            value = operation(candidate);
             _store.Save(candidate);
         }
         catch (Exception exception)
@@ -120,32 +143,12 @@ public SettingsCommitResult<T> Commit<T>(
         }
 
         _current.ReplaceWith(candidate);
-        Changed?.Invoke(this, EventArgs.Empty);
-        return SettingsCommitResult<T>.Success(value);
-    }
-
-    public SettingsCommitResult PersistCurrent()
-    {
-        var candidate = _current.CreateWorkingCopy();
-
-        try
-        {
-            _store.Save(candidate);
-        }
-        catch (Exception exception)
-            when (IsExpectedError(exception))
+        if (publishChanged)
         {
-            return SettingsCommitResult.Failure(
-                FormatError(exception));
-        }
-        catch (Exception exception)
-        {
-            _reportUnexpectedError(exception);
-            throw;
+            Changed?.Invoke(this, EventArgs.Empty);
         }
 
-        _current.ReplaceWith(candidate);
-        return SettingsCommitResult.Success();
+        return SettingsCommitResult<T>.Success(value);
     }
 
     private static bool IsExpectedError(

src/SightAdapt/SettingsUseCaseContext.cs

@@ -0,0 +1,33 @@
+namespace SightAdapt;
+
+internal sealed class SettingsUseCaseContext
+{
+    private readonly SettingsCoordinator _coordinator;
+
+    public SettingsUseCaseContext(
+        SettingsCoordinator coordinator)
+    {
+        _coordinator = coordinator ??
+            throw new ArgumentNullException(nameof(coordinator));
+    }
+
+    public IReadOnlySightAdaptSettings Snapshot =>
+        _coordinator.Current;
+
+    public string SettingsPath =>
+        _coordinator.SettingsPath;
+
+    public event EventHandler? Changed
+    {
+        add => _coordinator.Changed += value;
+        remove => _coordinator.Changed -= value;
+    }
+
+    public SettingsCommitResult Commit(
+        Action<SightAdaptSettings> mutation) =>
+        _coordinator.Commit(mutation);
+
+    public SettingsCommitResult<T> Commit<T>(
+        Func<SightAdaptSettings, T> mutation) =>
+        _coordinator.Commit(mutation);
+}

src/SightAdapt/VisualProfileUseCases.cs

@@ -2,23 +2,31 @@ namespace SightAdapt;
 
 internal sealed class VisualProfileUseCases
 {
-    private readonly SettingsCoordinator _settingsCoordinator;
+    private readonly SettingsUseCaseContext _settings;
 
     public VisualProfileUseCases(
         SettingsCoordinator settingsCoordinator)
-    {
-        _settingsCoordinator = settingsCoordinator ??
+        : this(new SettingsUseCaseContext(
+            settingsCoordinator ??
             throw new ArgumentNullException(
-                nameof(settingsCoordinator));
+                nameof(settingsCoordinator))))
+    {
+    }
+
+    internal VisualProfileUseCases(
+        SettingsUseCaseContext settings)
+    {
+        _settings = settings ??
+            throw new ArgumentNullException(nameof(settings));
     }
 
-    public SightAdaptSettings Snapshot =>
-        _settingsCoordinator.Current;
+    public IReadOnlySightAdaptSettings Snapshot =>
+        _settings.Snapshot;
 
     public event EventHandler? Changed
     {
-        add => _settingsCoordinator.Changed += value;
-        remove => _settingsCoordinator.Changed -= value;
+        add => _settings.Changed += value;
+        remove => _settings.Changed -= value;
     }
 
     public string CreateAvailableName(string baseName)
@@ -31,7 +39,7 @@ public string CreateAvailableName(string baseName)
 
     public SettingsCommitResult<string> Create(string name)
     {
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
             VisualProfileManagementService.Create(
                 settings,
                 name).Id);
@@ -43,7 +51,7 @@ public SettingsCommitResult<string> Duplicate(
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(sourceProfileId);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
             VisualProfileManagementService.Duplicate(
                 settings,
                 ProfileResolver.RequireVisualProfile(
@@ -58,7 +66,7 @@ public SettingsCommitResult<string> Rename(
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(profileId);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             VisualProfileManagementService.Rename(
                 settings,
@@ -77,7 +85,7 @@ public SettingsCommitResult<string> UpdateTuning(
         ArgumentException.ThrowIfNullOrWhiteSpace(profileId);
         ArgumentNullException.ThrowIfNull(values);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             VisualProfileManagementService.UpdateTuning(
                 settings,
@@ -97,7 +105,7 @@ public SettingsCommitResult<string> Delete(
         ArgumentException.ThrowIfNullOrWhiteSpace(
             fallbackProfileId);
 
-        return _settingsCoordinator.Commit(settings =>
+        return _settings.Commit(settings =>
         {
             VisualProfileManagementService.Delete(
                 settings,