import Foundation /// Limits cover the native worker pool; queue limits cover waiting input data. /// Defaults leave 6 GiB available for macOS and other applications. public struct EngineConfiguration: Sendable, Codable { public var maxConcurrentWorkers = 1 public var maxQueuedRequests = 128 public var maxQueuedBytes = 128 * 1_024 * 1_024 public var maxTotalWorkerRSSBytes: UInt64 = 4 * 1_024 * 1_024 * 1_024 public var maxWorkerRSSBytes: UInt64 = 3 * 1_024 * 1_024 * 1_024 public var minimumSystemAvailableBytes: UInt64 = 6 * 1_024 * 1_024 * 1_024 public var keepWarmSeconds: Double = 60 public var maxRequestsPerWorker = 128 public var requestTimeoutSeconds: Double = 120 public var cacheMode: WorkerMode = .adaptive public var memoryCheckIntervalSeconds: Double = 0.1 /// Input + output + attention admission estimate, checked before allocation. public var maxRequestWorkingBytes: UInt64 = 2 * 1_024 * 1_024 * 1_024 public init() {} func validate() throws { guard maxConcurrentWorkers > 0, maxQueuedRequests > 0, maxQueuedBytes > 0, maxTotalWorkerRSSBytes > 0, maxWorkerRSSBytes > 0, maxWorkerRSSBytes <= maxTotalWorkerRSSBytes, maxRequestsPerWorker > 0, keepWarmSeconds.isFinite, keepWarmSeconds >= 0, requestTimeoutSeconds.isFinite, requestTimeoutSeconds > 0, memoryCheckIntervalSeconds.isFinite, memoryCheckIntervalSeconds >= 0.02, maxRequestWorkingBytes > 0 else { throw EngineError.invalidConfiguration("Limits must be positive; idle retention may be zero and the memory polling interval must be at least 0.02 seconds.") } } } public enum EngineError: Error, Sendable, LocalizedError { case invalidConfiguration(String) case unknownModel(String) case queueFull(requests: Int, bytes: Int) case requestTooLarge(estimatedBytes: UInt64, limit: UInt64) case insufficientMemory(available: UInt64, required: UInt64) case memoryLimit(String) case timedOut case workerFailed(String) case shutDown case offloaded public var errorDescription: String? { switch self { case .invalidConfiguration(let text): return text case .unknownModel(let name): return "No registered Timestral model named \(name)." case .queueFull(let count, let bytes): return "Timestral queue is full (\(count) waiting requests, \(bytes) bytes). Use bounded producers or retry after capacity is available." case .requestTooLarge(let bytes, let limit): return "Estimated request working set \(bytes) bytes exceeds the configured \(limit)-byte limit." case .insufficientMemory(let free, let reserve): return "Available system memory \(free) bytes is below the required \(reserve)-byte reserve." case .memoryLimit(let detail): return "Timestral stopped a worker at its memory limit: \(detail)" case .timedOut: return "Timestral request exceeded its time limit." case .workerFailed(let detail): return "Timestral native worker failed: \(detail)" case .shutDown: return "Timestral engine is shut down." case .offloaded: return "The requested model was explicitly offloaded." } } } /// Cumulative counters and a current pool snapshot. RSS is sampled, not a hard allocation cap. public struct EngineStatistics: Sendable, Codable { public internal(set) var queuedRequests = 0 public internal(set) var queuedBytes = 0 public internal(set) var activeRequests = 0 public internal(set) var warmWorkers = 0 public internal(set) var workersStarted = 0 public internal(set) var workersRecycled = 0 public internal(set) var completedRequests = 0 public internal(set) var failedRequests = 0 public internal(set) var cancelledRequests = 0 public internal(set) var rejectedRequests = 0 public internal(set) var currentWorkerRSSBytes: UInt64 = 0 public internal(set) var peakWorkerRSSBytes: UInt64 = 0 public internal(set) var minimumObservedSystemAvailableBytes: UInt64 = .max public internal(set) var totalQueueWaitSeconds: Double = 0 public internal(set) var totalExecutionSeconds: Double = 0 public init() {} }