Deprecate JournalOptions.Adapters property in favor of callback API (#669)

* Deprecate JournalOptions.Adapters property in favor of callback API

Fixes #665

The Adapters property created confusion by providing two competing
patterns for configuring event adapters. This deprecates the property
in favor of the unified callback pattern introduced in PR #662.

Changes:
- Mark JournalOptions.Adapters as [Obsolete] with clear migration message
- Remove internal usage of the property (Adapters.AppendAdapters call)
- Add regression test DeprecatedAdaptersPropertySpec that verifies:
  * Deprecated property is ignored and does not configure adapters
  * Callback pattern continues to work correctly
  * Uses #pragma warning disable to test deprecated API

Benefits:
- Single, consistent pattern for configuring adapters and health checks
- Cleaner API surface with options containing only configuration data
- Clear migration path with deprecation warning

Migration:
Before (deprecated):
  var options = new JournalOptions();
  options.Adapters.AddWriteEventAdapter<Foo>(...);
  builder.WithJournal(options);

After (recommended):
  var options = new JournalOptions();
  builder.WithJournal(options, journal =>
    journal.AddWriteEventAdapter<Foo>(...));

All 17 tests pass.

* added API approvals

Author: Aaronontheweb

src/Akka.Hosting.API.Tests/verify/CoreApiSpec.ApprovePersistence.verified.txt

@@ -43,6 +43,9 @@ namespace Akka.Persistence.Hosting
     public abstract class JournalOptions
     {
         protected JournalOptions(bool isDefault) { }
+        [System.Obsolete("Use the configureBuilder callback parameter in WithJournal() instead. This proper" +
+            "ty will be removed in v1.6.0. See https://github.com/akkadotnet/Akka.Hosting/iss" +
+            "ues/665")]
         public Akka.Persistence.Hosting.AkkaPersistenceJournalBuilder Adapters { get; set; }
         public bool AutoInitialize { get; set; }
         public Akka.Configuration.Config DefaultConfig { get; }

src/Akka.Persistence.Hosting.Tests/EventAdapterSpecs.cs

@@ -129,4 +129,79 @@ public void Should_use_correct_EventAdapter_bindings()
         sqlPersistenceJournal.GetString("event-adapters.combo").Should().Be(typeof(ComboAdapter).TypeQualifiedName());
         sqlPersistenceJournal.GetString("event-adapters.tagger").Should().Be(typeof(Tagger).TypeQualifiedName());
     }
+}
+
+/// <summary>
+/// Regression test for https://github.com/akkadotnet/Akka.Hosting/issues/665
+/// Verifies that the deprecated Adapters property is ignored and does not configure event adapters
+/// </summary>
+public class DeprecatedAdaptersPropertySpec : Akka.Hosting.TestKit.TestKit
+{
+    private sealed class TestJournalOptions : JournalOptions
+    {
+        public TestJournalOptions() : base(isDefault: true)
+        {
+            Identifier = "test-journal";
+        }
+
+        public override string Identifier { get; set; }
+
+        protected override Config InternalDefaultConfig =>
+            ConfigurationFactory.ParseString(@"
+                class = ""Akka.Persistence.Journal.MemoryJournal, Akka.Persistence""
+                plugin-dispatcher = ""akka.actor.default-dispatcher""
+            ");
+    }
+
+    public sealed class DeprecatedAdapter : IWriteEventAdapter
+    {
+        public string Manifest(object evt) => string.Empty;
+        public object ToJournal(object evt) => evt;
+    }
+
+    public sealed class CallbackAdapter : IWriteEventAdapter
+    {
+        public string Manifest(object evt) => string.Empty;
+        public object ToJournal(object evt) => evt;
+    }
+
+    protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
+    {
+        var journalOptions = new TestJournalOptions();
+
+#pragma warning disable 618, 619
+        // Attempt to use the deprecated Adapters property
+        journalOptions.Adapters = new AkkaPersistenceJournalBuilder("test-journal", builder);
+        journalOptions.Adapters.AddWriteEventAdapter<DeprecatedAdapter>("deprecated-adapter",
+            new[] { typeof(string) });
+#pragma warning restore 618, 619
+
+        // Use the callback pattern (the correct way)
+        builder.WithJournal(journalOptions, journal =>
+            journal.AddWriteEventAdapter<CallbackAdapter>("callback-adapter",
+                new[] { typeof(int) }));
+    }
+
+    [Fact]
+    public void Deprecated_Adapters_property_should_be_ignored()
+    {
+        var config = Sys.Settings.Config;
+        var journalConfig = config.GetConfig("akka.persistence.journal.test-journal");
+
+        // The deprecated adapter should NOT be registered
+        journalConfig.HasPath("event-adapters.deprecated-adapter").Should().BeFalse(
+            "adapters configured via the deprecated Adapters property should be ignored");
+
+        // The callback adapter SHOULD be registered
+        journalConfig.HasPath("event-adapters.callback-adapter").Should().BeTrue(
+            "adapters configured via the callback pattern should work");
+        journalConfig.GetString("event-adapters.callback-adapter")
+            .Should().Be(typeof(CallbackAdapter).TypeQualifiedName());
+
+        // Verify bindings
+        journalConfig.HasPath($"event-adapter-bindings.\"{typeof(string).TypeQualifiedName()}\"")
+            .Should().BeFalse("deprecated adapter bindings should not exist");
+        journalConfig.GetStringList($"event-adapter-bindings.\"{typeof(int).TypeQualifiedName()}\"")
+            .Should().BeEquivalentTo(new[] { "callback-adapter" }, "callback adapter bindings should exist");
+    }
 }

src/Akka.Persistence.Hosting/JournalOptions.cs

@@ -75,6 +75,7 @@ protected JournalOptions(bool isDefault)
         /// The journal adapter builder, use this builder to add custom journal
         /// <see cref="IEventAdapter"/>, <see cref="IWriteEventAdapter"/>, or <see cref="IReadEventAdapter"/>
         /// </summary>
+        [Obsolete("Use the configureBuilder callback parameter in WithJournal() instead. This property will be removed in v1.6.0. See https://github.com/akkadotnet/Akka.Hosting/issues/665")]
         public AkkaPersistenceJournalBuilder Adapters { get; set; } = new ("", null!);
 
         public string PluginId => $"akka.persistence.journal.{Identifier}";
@@ -102,7 +103,8 @@ protected virtual StringBuilder Build(StringBuilder sb)
             sb.Insert(0, $"{PluginId} {{{Environment.NewLine}");
             sb.AppendLine($"auto-initialize = {AutoInitialize.ToHocon()}");
             sb.AppendLine($"serializer = {Serializer.ToHocon()}");
-            Adapters.AppendAdapters(sb);
+            // Adapters property is deprecated - use the callback pattern in WithJournal() instead
+            // See https://github.com/akkadotnet/Akka.Hosting/issues/665
             sb.AppendLine("}");
 
             if (IsDefaultPlugin)