field_ios

TeraComposerAutosave.swift (12280B)

---

 import Foundation
 
 /// A transient write barrier; its token is never a durable submission identity.
 struct TeraComposerCapture: Sendable, Equatable {
   let token: UUID
   let scope: TeraComposerScope
   let form: TeraComposerForm
   let editSequence: UInt64
 }
 
 /// A single worker retains one attempted write and the newest edit. Receipts
 /// update acknowledgment metadata only; they never replace the editing form.
 @MainActor
 final class TeraComposerAutosave {
   private(set) var state: TeraComposerSaveState = .idle {
     didSet {
       if state != oldValue {
         stateChanged(state)
       }
     }
   }
 
   var stateChanged: (TeraComposerSaveState) -> Void = { _ in }
   private(set) var acknowledged: TeraComposerDraft?
   private(set) var scope: TeraComposerScope?
   private(set) var editSequence: UInt64 = 0
   private(set) var id: String?
   private let persistence: TeraComposerPersistence
   private let delay: @Sendable () async throws -> Void
   private var generation = TeraSessionGeneration.initial
   private var current: TeraComposerForm?
   private var attempted: TeraComposerSaveRequest?
   private var worker: Task<Void, Never>?
   private var coalescingTask: Task<Void, Error>?
   private var immediateSave = false
   private var lastFailure: Error?
   private var paused = false
   private var exhausted = false
   private var capture: TeraComposerCapture?
 
   init(
     persistence: TeraComposerPersistence,
     delay: @escaping @Sendable () async throws -> Void = { try await Task.sleep(for: .milliseconds(250)) }
   ) {
     self.persistence = persistence
     self.delay = delay
   }
 
   deinit {
     coalescingTask?.cancel()
     worker?.cancel()
   }
 
   var isDirty: Bool {
     current != nil && (exhausted || acknowledged?.editSequence != editSequence || acknowledged?.form != current)
   }
 
   private var needsWrite: Bool {
     if let capture {
       return !matchesCapture(acknowledged, capture)
     }
     return isDirty
   }
 
   private func matchesCapture(_ draft: TeraComposerDraft?, _ value: TeraComposerCapture) -> Bool {
     draft?.scope == value.scope && draft?.editSequence == value.editSequence && draft?.form == value.form
   }
 
   /// A replaced scope or New operation invalidates callbacks, but keeps the
   /// worker slot occupied until it exits, preventing abandoned task fan-out.
   func reset(scope: TeraComposerScope?) {
     generation = generation.invalidated()
     immediateSave = false
     coalescingTask?.cancel()
     worker?.cancel()
     self.scope = scope
     id = nil
     current = nil
     acknowledged = nil
     attempted = nil
     lastFailure = nil
     editSequence = 0
     exhausted = false
     capture = nil
     paused = false
     state = .idle
   }
 
   func stop() {
     generation = generation.invalidated()
     paused = true
     immediateSave = false
     coalescingTask?.cancel()
     worker?.cancel()
     if isDirty {
       state = .unsaved
     }
   }
 
   func resume() {
     paused = false
     startWorker()
   }
 
   func restore(_ draft: TeraComposerDraft) throws {
     guard draft.scope == scope, TeraAddPresentation.isValidIdentifier(draft.id),
           draft.id != String(repeating: "0", count: 32), draft.revision > 0,
           draft.revision <= UInt64(Int64.max), draft.editSequence > 0
     else {
       throw TeraComposerAcknowledgment.unconfirmed
     }
     reset(scope: draft.scope)
     id = draft.id
     editSequence = draft.editSequence
     current = draft.form
     acknowledged = draft
     state = .saved
   }
 
   func change(_ form: TeraComposerForm) {
     guard form != current else { return }
     current = form
     let (next, overflow) = editSequence.addingReportingOverflow(1)
     guard !overflow, !exhausted else {
       exhausted = true
       state = .failed
       return
     }
     editSequence = next
     if state != .failed {
       state = .unsaved
     }
     startWorker()
   }
 
   func observeEditing(_ form: TeraAddForm, isEditable: Bool, isRevision: Bool) {
     guard isEditable, !isRevision else {
       stop()
       state = isRevision ? .revision : .idle
       return
     }
     change(TeraComposerForm(editing: form))
   }
 
   func save(_ form: TeraComposerForm) async throws -> TeraComposerDraft {
     guard !Task.isCancelled else { throw CancellationError() }
     change(form)
     guard capture == nil else {
       throw TeraRuntimeFailure.local(operation: "composer.save", code: "submission_capture_pending",
                                      safeMessage: "The original submission must be reconciled before newer editing can be saved.")
     }
     guard !paused, !exhausted, generation.isActive, scope != nil else {
       state = .failed
       throw TeraComposerAcknowledgment.unconfirmed
     }
     let requested = generation
     if state == .failed {
       state = .unsaved
     }
     if isDirty {
       immediateSave = true
       coalescingTask?.cancel()
     }
     startWorker()
     while let task = worker {
       if isDirty {
         immediateSave = true
         coalescingTask?.cancel()
       }
       await task.value
       try ensureCurrent(requested)
     }
     guard !isDirty, let acknowledged else { throw lastFailure ?? TeraComposerAcknowledgment.unconfirmed }
     try await confirmSaved(acknowledged, generation: requested)
     guard !isDirty else { throw TeraComposerAcknowledgment.unconfirmed }
     return acknowledged
   }
 
   private func startWorker() {
     guard worker == nil, !paused, !exhausted, generation.isActive, scope != nil,
           needsWrite, state != .failed else { return }
     let requested = generation
     lastFailure = nil
     worker = Task { [weak self] in
       guard let self else { return }
       await run(requested)
     }
   }
 
   private func run(_ requested: TeraSessionGeneration) async {
     defer {
       if generation == requested {
         immediateSave = false
       }
       worker = nil
       startWorker()
     }
     do {
       while needsWrite {
         try ensureCurrent(requested)
         state = .saving
         try await coalesce(requested)
         try ensureCurrent(requested)
         try await reconcileAttempt(requested)
         try await persistCurrent(requested)
       }
       try ensureCurrent(requested)
       state = isDirty ? .unsaved : .saved
     } catch {
       // A write may have committed before cancellation or a lost callback.
       // Keep its exact request for a read before any retry in this lifetime.
       if generation == requested, !paused {
         lastFailure = error
         state = .failed
       }
     }
   }
 
   private func coalesce(_ requested: TeraSessionGeneration) async throws {
     guard !immediateSave else { return }
     let task = Task { [delay] in try await delay() }
     coalescingTask = task
     defer { coalescingTask = nil }
     do {
       try await task.value
     } catch {
       try ensureCurrent(requested)
       // Explicit Save cancels only batching; an in-flight write still owns
       // its slot until its receipt or unknown-write reconciliation completes.
       guard immediateSave, error is CancellationError else { throw error }
     }
   }
 
   private func persistCurrent(_ requested: TeraSessionGeneration) async throws {
     if id == nil {
       let reserved = try await persistence.reserve()
       try ensureCurrent(requested)
       guard TeraAddPresentation.isValidIdentifier(reserved), reserved != String(repeating: "0", count: 32) else {
         throw TeraComposerAcknowledgment.unconfirmed
       }
       id = reserved
     }
     guard needsWrite, let id, let scope, let current else { return }
     let request = TeraComposerSaveRequest(scope: scope, id: id, expectedRevision: acknowledged?.revision,
                                           editSequence: capture?.editSequence ?? editSequence, form: capture?.form ?? current)
     attempted = request
     let receipt = try await persistence.save(request)
     try ensureCurrent(requested)
     guard TeraComposerAcknowledgment.matches(receipt.draft, request: request) else {
       throw TeraComposerAcknowledgment.unconfirmed
     }
     acknowledged = receipt.draft
     attempted = nil
   }
 
   private func reconcileAttempt(_ requested: TeraSessionGeneration) async throws {
     guard let attempted else { return }
     let loaded: TeraComposerDraft
     do {
       loaded = try await persistence.load(attempted.scope, attempted.id)
     } catch {
       try ensureCurrent(requested)
       if attempted.expectedRevision == nil,
          TeraAddPresentation.failure(for: error)?.code == "composer_not_found"
       {
         self.attempted = nil
         return
       }
       throw error
     }
     try ensureCurrent(requested)
     if TeraComposerAcknowledgment.matches(loaded, request: attempted) {
       acknowledged = loaded
     } else if loaded != acknowledged {
       // A different writer won the CAS. Preserve this form for recovery;
       // silently adopting its revision would overwrite someone else's edit.
       throw TeraComposerAcknowledgment.unconfirmed
     }
     self.attempted = nil
   }
 
   private func ensureCurrent(_ requested: TeraSessionGeneration) throws {
     guard generation == requested, generation.isActive, !paused, !exhausted, !Task.isCancelled else {
       throw CancellationError()
     }
   }
 }
 
 /// Capture scheduling shares the private autosave worker; it owns no second persistence path.
 extension TeraComposerAutosave {
   private func confirmSaved(_ draft: TeraComposerDraft, generation requested: TeraSessionGeneration) async throws {
     do {
       try await persistence.confirm(draft)
       try ensureCurrent(requested)
       guard acknowledged == draft else { throw TeraComposerAcknowledgment.unconfirmed }
       if !isDirty {
         state = .saved
       }
     } catch {
       if generation == requested {
         state = .failed
         lastFailure = error
       }
       throw error
     }
   }
 
   var hasSubmissionCapture: Bool {
     capture != nil
   }
 
   /// Reserve synchronously with the tap, before either worker can await.
   func beginSubmissionCapture(_ form: TeraComposerForm) throws -> TeraComposerCapture {
     guard capture == nil, !paused, !exhausted, generation.isActive, let scope else {
       throw TeraComposerAcknowledgment.unconfirmed
     }
     change(form)
     guard !exhausted else { throw TeraComposerAcknowledgment.unconfirmed }
     let value = TeraComposerCapture(token: UUID(), scope: scope, form: form, editSequence: editSequence)
     capture = value
     if state == .failed {
       state = .unsaved
     }
     immediateSave = true
     coalescingTask?.cancel()
     startWorker()
     return value
   }
 
   /// Reconcile an existing write, then persist only this captured edit. Later
   /// edits remain visible and unsaved until the caller releases the barrier.
   func saveSubmissionCapture(_ value: TeraComposerCapture) async throws -> TeraComposerDraft {
     guard capture == value else { throw TeraComposerAcknowledgment.unconfirmed }
     let requested = generation
     try ensureCurrent(requested)
     if state == .failed {
       state = .unsaved
     }
     immediateSave = true
     coalescingTask?.cancel()
     startWorker()
     while let task = worker {
       await task.value
       try ensureCurrent(requested)
     }
     guard capture == value, let acknowledged, matchesCapture(acknowledged, value) else {
       throw lastFailure ?? TeraComposerAcknowledgment.unconfirmed
     }
     try await confirmSaved(acknowledged, generation: requested)
     return acknowledged
   }
 
   /// Call only after submission commit/recovery is confirmed, or an explicit
   /// decision abandons a request known not to have committed.
   func releaseSubmissionCapture(_ value: TeraComposerCapture) {
     guard capture == value else { return }
     capture = nil
     if isDirty {
       state = .unsaved
       immediateSave = true
       startWorker()
     }
   }
 
   /// A confirmed Rust reservation owns the original source head. Continue
   /// editing through the same persistence worker under a fresh composer ID;
   /// never overwrite the revision required by the original prepare CAS.
   func continueEditing(after value: TeraComposerCapture, reserved: TeraComposerDraft) throws {
     guard capture == value, acknowledged == reserved, matchesCapture(reserved, value),
           let current, worker == nil, attempted == nil
     else {
       throw TeraComposerAcknowledgment.unconfirmed
     }
     reset(scope: value.scope)
     change(current)
   }
 }