docs: condense implementation comments

clients/apple/Sources/VoiceCatCore/Callbacks.swift

@@ -1,19 +1,5 @@
-// Callbacks — the C function pointers passed to `vc_callbacks`. These are the Swift
-// equivalent of the C# client's `[UnmanagedCallersOnly]` static methods (NativeCallbacks.cs).
-//
-// The critical patterns (carried over from the proven C# implementation):
-//   1. `@convention(c)` closures — plain C function pointers, NOT GC/ARC-managed closures.
-//      A @convention(c) closure cannot capture context, which is why the `user` pointer is
-//      used to resolve back to the VoiceCatClient instance (the C# version uses GCHandle for
-//      the same thing; Swift uses Unmanaged).
-//   2. `Unmanaged.passUnretained(self).toOpaque()` as the `user` context — a stable raw
-//      pointer to the Swift object WITHOUT incrementing the retain count. This is safe
-//      because `deinit` calls `vc_client_destroy` (which synchronously joins every internal
-//      thread) BEFORE the object's memory is freed — so no callback can fire after the object
-//      is gone. (The C# equivalent: GCHandle.Alloc + GCHandle.Free in Dispose.)
-//   3. Copy `ev.text` to a Swift `String` INSIDE `onEvent` (via `VoiceCatEvent.from(_:)`)
-//      before returning — the raw pointer is dangling after the callback returns. This is
-//      the #1 lifetime rule from voicecat.h's vc_event doc comment.
+// C callbacks use an unretained `user` context. Client destruction joins callback threads,
+// and transient event pointers are copied before the callback returns.
 
 import VoiceCatC
 import Foundation

clients/apple/Sources/VoiceCatCore/VoiceCatClient.swift

@@ -1,36 +1,6 @@
-// VoiceCatClient — the public, Swift-idiomatic surface over libvoicecat. This is the Swift
-// analog of the C# client's `VoiceCatClient.cs` (clients/windows/VoiceCat.Interop).
-//
-// Key patterns carried over from the proven C# implementation (see docs/architecture.md §4
-// per-platform binding notes):
-//
-//   1. HANDLE OWNERSHIP: the class owns `vc_client*`; `deinit` calls `vc_client_destroy`
-//      (which synchronously joins every internal thread, so nothing can still be reading the
-//      config-string pointers or firing callbacks by the time it returns).
-//
-//   2. CONFIG STRING LIFETIMES: the core stores raw pointers from `vc_config` by value — it
-//      does NOT copy the string data. `client_name`/`client_version`/`tofu_store_path` are
-//      read later, whenever `connect()` actually runs on the io_thread_. So the native CString
-//      storage (`_clientNamePtr` etc.) must outlive the WHOLE client, not just `init`. It's
-//      freed in `deinit`, AFTER `vc_client_destroy` has returned. (C#: Marshal.StringToCoTask
-//      MemUTF8 in ctor, FreeCoTaskMem in Dispose after destroy.)
-//
-//   3. EVENT DELIVERY THREAD HANDOFF: `on_event` fires on the core's event thread. Events are
-//      buffered in a lock-protected array and drained on `DispatchQueue.main` — this is the
-//      boundary where the core's thread hands off to the UI thread. The C# analog is
-//      `Channel<VoiceCatEvent>` drained by a 30ms WinForms Timer; the Swift analog is a
-//      coalesced main-queue drain (only one async block scheduled at a time). `on_event`'s
-//      `text` is copied to a Swift `String` inside the callback (Callbacks.swift) before
-//      enqueueing — the raw pointer is dangling by the time the main thread drains.
-//
-//   4. LEVEL METER COALESCING: `on_level` fires far more often than `on_event` and
-//      intermediate values are visually irrelevant — coalesced to "latest sample per
-//      stream_id" in a lock-protected dictionary, drained on main alongside events.
-//      (C#: ConcurrentDictionary<uint,float> cleared in PumpEvents.)
-//
-//   5. IMMEDIATE vc_free_* ON LIST READS: `listChannels()`/`listUsers()`/etc. walk the native
-//      array, convert to Swift value types, and call `vc_free_*_list` INSIDE the function —
-//      callers never manage native list lifetime. (C#: Marshaling.ToManaged does the same.)
+// Swift binding invariants: native config strings outlive the handle, destroy joins callback
+// threads before deallocation, and callback payloads are copied before main-queue delivery.
+// See docs/architecture.md §4 for the complete binding contract.
 
 import VoiceCatC
 import Foundation
@@ -56,26 +26,14 @@ public final class VoiceCatClient {
 
     // MARK: - Stored properties
 
-    /// The opaque C handle (`vc_client*` — Swift imports the incomplete C struct as
-    /// `OpaquePointer`). Set in `init`, passed to every C function, destroyed in `deinit`.
     private var handle: OpaquePointer?
 
-    /// Unmanaged pointer to `self` — passed as `vc_callbacks.user` so the C function-pointer
-    /// callbacks can resolve back to this instance. `passUnretained` (not `passRetained`)
-    /// because we want normal ARC to control the object's lifetime — `deinit` calls
-    /// `vc_client_destroy` (joins all threads) before the object's memory is freed, so no
-    /// callback can fire with a dangling `user` pointer. See Callbacks.swift.
-    ///
-    /// Computed (not stored) to break a circular init dependency: it needs `self`, but
-    /// stored properties must be initialized before `self` is available. `Unmanaged.passUn
-    /// retained(self).toOpaque()` always returns the same address for a given instance, so
-    /// computing it on demand is safe and consistent.
+    /// Unretained callback context; destroying the handle joins callback threads first.
     private var selfPointer: UnsafeMutableRawPointer {
         Unmanaged.passUnretained(self).toOpaque()
     }
 
-    /// Native CString storage backing `vc_config` — must outlive the whole client (the core
-    /// stores raw pointers, doesn't copy). Freed in `deinit` after `vc_client_destroy`.
+    /// The core retains these pointers for the handle's lifetime.
     private var clientNamePtr: UnsafeMutablePointer<CChar>?
     private var clientVersionPtr: UnsafeMutablePointer<CChar>?
     private var tofuStorePathPtr: UnsafeMutablePointer<CChar>?
@@ -90,7 +48,6 @@ public final class VoiceCatClient {
     /// Intermediate values are coalesced (only the latest per stream_id is delivered).
     public var onLevel: ((UInt32, Float) -> Void)?
 
-    /// Lock-protected buffers, written from the core's event thread, drained on main.
     private let bufferLock = NSLock()
     private var eventBuffer: [VoiceCatEvent] = []
     private var levelSamples: [UInt32: Float] = [:]
@@ -98,19 +55,12 @@ public final class VoiceCatClient {
 
     // MARK: - Init / deinit
 
-    /// Create a client. `config.clientName`/`clientVersion`/`tofuStorePath` are copied to
-    /// native CString storage held for the client's entire lifetime (the core reads them
-    /// later, e.g. when `connect()` runs on the io thread).
     public init(config: VoiceCatConfig) {
-        // Allocate native C strings — must persist until after vc_client_destroy in deinit.
-        // These don't need `self`, so they're safe to set first.
         self.clientNamePtr = strdup(config.clientName)
         self.clientVersionPtr = strdup(config.clientVersion)
         self.tofuStorePathPtr = config.tofuStorePath.flatMap { strdup($0) }
         self.handle = nil  // placeholder — set below after callbacks are wired
 
-        // All stored properties are now initialized → `self` is fully available, so we can
-        // call `selfPointer` (the computed property) to build the callbacks struct.
         var nativeConfig = vc_config()
         nativeConfig.client_name = UnsafePointer(clientNamePtr)
         nativeConfig.client_version = UnsafePointer(clientVersionPtr)