// SPDX-License-Identifier: GPL-3.0-or-later import Foundation import Darwin /// Public processor choices are guest CPUs, independent of the Mac's host /// architecture. Selection never sets the HD6309 MD register for the guest. enum MCPPlaytestProcessor: String, Sendable { case mc6809 = "MC6809" case hd6309 = "HD6309" var workerCPU: String { self == .hd6309 ? "6309" : "6809" } static func selected(_ value: Any?) throws -> Self { guard let value else { return .mc6809 } guard let name = value as? String, let processor = Self(rawValue: name) else { throw ProfileFailure.message("invalid_playtest_processor") } return processor } } /// Validated complete standard-joystick snapshots. Coordinates use the same /// 14-bit input range as the native host; they never address guest memory. enum MCPPlaytestJoystick { static func snapshots(_ value: Any) throws -> [[String: Any]] { guard let values = value as? [[String: Any]], values.count <= 2 else { throw ProfileFailure.message("invalid_playtest_joystick") } var seen = Set() return try values.map { item in guard Set(item.keys) == ["port", "x", "y", "buttons"], let port = item["port"] as? String, ["right", "left"].contains(port), seen.insert(port).inserted, let x = axis(item["x"]), let y = axis(item["y"]), let buttons = item["buttons"] as? [String], buttons.count <= 2, Set(buttons).count == buttons.count, buttons.allSatisfy({ ["fire1", "fire2"].contains($0) }) else { throw ProfileFailure.message("invalid_playtest_joystick") } return ["port": port, "x": x, "y": y, "buttons": buttons] } } private static func axis(_ value: Any?) -> Int? { guard let value = value as? NSNumber, CFGetTypeID(value) != CFBooleanGetTypeID(), value.doubleValue.isFinite, (0...16383).contains(value.doubleValue), value.doubleValue.rounded(.towardZero) == value.doubleValue else { return nil } return value.intValue } } /// Durable app-owned playtest disks. A UUID directory is published in one rename /// only after its immutable disk and provenance sidecar have both been synced. /// Legacy flat UUID.dsk files require an exact prior receipt and are never listed. struct MCPPlaytestDiskStore: Sendable { struct Provenance: Codable, Equatable, Sendable { let projectKey: String? let artifactID: String? let artifactDiskSHA256: String? let parentDiskID: String? let origin: String let originArtifactID: String? let originArtifactDiskSHA256: String? let mediaKey: String? let mediaBaseSHA256: String? init(projectKey: String?, artifactID: String?, artifactDiskSHA256: String?, parentDiskID: String? = nil, origin: String = "verified_artifact", originArtifactID: String? = nil, originArtifactDiskSHA256: String? = nil, mediaKey: String? = nil, mediaBaseSHA256: String? = nil) { self.projectKey = projectKey; self.artifactID = artifactID; self.artifactDiskSHA256 = artifactDiskSHA256 self.parentDiskID = parentDiskID; self.origin = origin self.originArtifactID = originArtifactID ?? (origin == "verified_artifact" ? artifactID : nil) self.originArtifactDiskSHA256 = originArtifactDiskSHA256 ?? (origin == "verified_artifact" ? artifactDiskSHA256 : nil) self.mediaKey = mediaKey; self.mediaBaseSHA256 = mediaBaseSHA256 } var publicFields: [String: Any] { var fields: [String: Any] = ["artifact_id": artifactID as Any? ?? NSNull(), "artifact_disk_sha256": artifactDiskSHA256 as Any? ?? NSNull(), "origin": origin, "origin_artifact_id": originArtifactID as Any? ?? NSNull(), "origin_artifact_disk_sha256": originArtifactDiskSHA256 as Any? ?? NSNull()] if let parentDiskID { fields["parent_disk_id"] = parentDiskID } fields["media_key"] = mediaKey ?? "primary" fields["media_base_sha256"] = (mediaBaseSHA256 ?? artifactDiskSHA256) as Any? ?? NSNull() return fields } } struct Record: Codable, Equatable, Sendable { let version: Int let id: String let runID: String let diskSHA256: String let provenance: Provenance let createdAt: Date? let byteCount: Int var publicFields: [String: Any] { var fields = provenance.publicFields fields["retained_disk_id"] = id; fields["run_id"] = runID fields["disk_sha256"] = diskSHA256; fields["byte_count"] = byteCount fields["created_at"] = createdAt.map { ISO8601DateFormatter().string(from: $0) } as Any? ?? NSNull() return fields } } private static let maximumDiskBytes = 512 * 1024 private static let maximumSidecarBytes = 16 * 1024 private static func failure(_ value: String) -> ProfileFailure { .message(value) } private static func identifier(_ value: String) throws -> String { guard value.utf8.count == 36, let uuid = UUID(uuidString: value), uuid.uuidString.lowercased() == value.lowercased() else { throw failure("invalid_retained_disk_id") } return uuid.uuidString } private static func digest(_ value: String) -> Bool { value.utf8.count == 64 && value.utf8.allSatisfy { (48...57).contains($0) || (97...102).contains($0) } } static func validate(_ provenance: Provenance) throws { guard let key = provenance.projectKey, digest(key), let artifact = provenance.artifactID, (try? identifier(artifact)) != nil, let artifactSHA = provenance.artifactDiskSHA256, digest(artifactSHA), ["verified_artifact", "legacy_receipt"].contains(provenance.origin) else { throw failure("invalid_playtest_disk_provenance") } if let parent = provenance.parentDiskID { _ = try identifier(parent) } if let key = provenance.mediaKey { guard !key.isEmpty, key.utf8.count <= 4096, let base = provenance.mediaBaseSHA256, digest(base) else { throw failure("invalid_playtest_media_provenance") } if key != "primary" { guard key.hasPrefix("disk:") else { throw failure("invalid_playtest_media_provenance") } try CMOCProject.validateRelativePath(String(key.dropFirst(5))) } } else if provenance.mediaBaseSHA256 != nil { throw failure("invalid_playtest_media_provenance") } if provenance.origin == "verified_artifact" { guard let original = provenance.originArtifactID, (try? identifier(original)) != nil, provenance.originArtifactDiskSHA256 == artifactSHA else { throw failure("invalid_playtest_disk_provenance") } } else { guard provenance.originArtifactID == nil, provenance.originArtifactDiskSHA256 == nil else { throw failure("invalid_legacy_disk_origin") } } } private static func canonicalDirectory(_ directory: URL) throws -> URL { let path = directory.standardizedFileURL.path guard path.hasPrefix("/"), !path.contains("\0") else { throw failure("invalid_playtest_disk_directory") } // macOS exposes /var and /tmp through system aliases. Normalize only // these known aliases; arbitrary links within an app-managed path fail. let normalized = path == "/var" || path.hasPrefix("/var/") || path == "/tmp" || path.hasPrefix("/tmp/") ? "/private" + path : path return URL(fileURLWithPath: normalized, isDirectory: true) } private static func directoryFD(_ directory: URL, create: Bool) throws -> (Int32, URL) { let root = try canonicalDirectory(directory) var current = open("/", O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW) guard current >= 0 else { throw POSIXError(.EIO) } do { for component in root.path.split(separator: "/") { let name = String(component) var next = openat(current, name, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW) if next < 0, errno == ENOENT, create { guard mkdirat(current, name, 0o700) == 0 || errno == EEXIST else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } next = openat(current, name, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW) } guard next >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } close(current); current = next } var info = stat() guard fstat(current, &info) == 0, info.st_mode & S_IFMT == S_IFDIR, info.st_uid == geteuid(), info.st_mode & 0o077 == 0 else { throw failure("invalid_playtest_disk_directory") } return (current, root) } catch { close(current); throw error } } private static func regularFD(_ parent: Int32, _ name: String, maximum: Int) throws -> (Int32, Int) { let fd = openat(parent, name, O_RDONLY | O_CLOEXEC | O_NOFOLLOW | O_NONBLOCK) guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } var info = stat() guard fstat(fd, &info) == 0, info.st_mode & S_IFMT == S_IFREG, info.st_uid == geteuid(), info.st_nlink == 1, info.st_size > 0, info.st_size <= off_t(maximum) else { close(fd); throw failure("invalid_retained_disk_file") } return (fd, Int(info.st_size)) } private static func read(_ parent: Int32, _ name: String, maximum: Int) throws -> Data { let (fd, size) = try regularFD(parent, name, maximum: maximum) defer { close(fd) } var result = Data(), buffer = [UInt8](repeating: 0, count: 16384) while true { let count = buffer.withUnsafeMutableBytes { Darwin.read(fd, $0.baseAddress, $0.count) } if count < 0, errno == EINTR { continue } guard count >= 0 else { throw POSIXError(.EIO) } if count == 0 { break } result.append(contentsOf: buffer.prefix(count)) guard result.count <= maximum else { throw failure("retained_disk_size_limit") } } guard result.count == size else { throw failure("retained_disk_changed") } return result } private static func childFD(_ parent: Int32, _ id: String) throws -> Int32 { let fd = openat(parent, id, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW) guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } var info = stat() guard fstat(fd, &info) == 0, info.st_mode & S_IFMT == S_IFDIR, info.st_uid == geteuid(), info.st_mode & 0o077 == 0 else { close(fd); throw failure("invalid_retained_disk_record") } return fd } private static func record(_ parent: Int32, id: String) throws -> Record { let decoder = JSONDecoder(); decoder.dateDecodingStrategy = .iso8601 let record = try decoder.decode(Record.self, from: read(parent, "record.json", maximum: maximumSidecarBytes)) guard [1, 2].contains(record.version), record.id == id, (try? identifier(record.runID)) == record.runID, (record.version == 2 || record.runID == id), digest(record.diskSHA256), (1...maximumDiskBytes).contains(record.byteCount), let created = record.createdAt, created.timeIntervalSince1970.isFinite, created.timeIntervalSince1970 > 0 else { throw failure("invalid_retained_disk_record") } try validate(record.provenance) let (disk, size) = try regularFD(parent, "disk.dsk", maximum: maximumDiskBytes) close(disk) guard size == record.byteCount else { throw failure("retained_disk_changed") } return record } /// Bounded metadata enumeration. A resume rechecks every disk byte against /// its receipt; listing does not hash hundreds of unrelated disk images. static func list(directory: URL, projectKey: String) async throws -> [Record] { guard digest(projectKey) else { throw failure("invalid_playtest_project_key") } return try await Task.detached { let parent: Int32 do { parent = try directoryFD(directory, create: false).0 } catch let error as POSIXError where error.code == .ENOENT { return [] } defer { close(parent) } guard let stream = fdopendir(dup(parent)) else { throw POSIXError(.EIO) } defer { closedir(stream) } var names: [String] = [], scanned = 0 while let entry = readdir(stream) { scanned += 1 guard scanned <= 4098 else { throw failure("playtest_disk_listing_limit") } let name = withUnsafePointer(to: &entry.pointee.d_name) { $0.withMemoryRebound(to: CChar.self, capacity: Int(NAME_MAX) + 1) { String(cString: $0) } } if let id = try? identifier(name), id == name { names.append(id) } } var records: [Record] = [] for id in names.sorted() { guard let fd = try? childFD(parent, id) else { continue } defer { close(fd) } guard let candidate = try? record(fd, id: id), candidate.provenance.projectKey == projectKey else { continue } records.append(candidate) } return Array(records.sorted { ($0.createdAt ?? .distantPast, $0.id) > ($1.createdAt ?? .distantPast, $1.id) }.prefix(1000)) }.value } static func load(directory: URL, id suppliedID: String, expectedSHA256: String, projectKey: String, artifactDiskSHA256: String, mediaKey: String = "primary", mediaBaseSHA256: String? = nil) async throws -> (data: Data, record: Record) { let id = try identifier(suppliedID) guard digest(expectedSHA256), digest(projectKey), digest(artifactDiskSHA256) else { throw failure("invalid_retained_disk_receipt") } return try await Task.detached { let (parent, _) = try directoryFD(directory, create: false) defer { close(parent) } var info = stat() if fstatat(parent, id, &info, AT_SYMLINK_NOFOLLOW) == 0 { let child = try childFD(parent, id); defer { close(child) } let stored = try record(child, id: id) guard stored.diskSHA256 == expectedSHA256, stored.provenance.projectKey == projectKey, stored.provenance.artifactDiskSHA256 == artifactDiskSHA256, (stored.provenance.mediaKey ?? "primary") == mediaKey, (mediaBaseSHA256 == nil || (stored.provenance.mediaBaseSHA256 ?? stored.provenance.artifactDiskSHA256) == mediaBaseSHA256) else { throw failure("retained_disk_provenance_mismatch") } let bytes = try read(child, "disk.dsk", maximum: maximumDiskBytes) guard CMOCProject.sha256(bytes) == expectedSHA256 else { throw failure("retained_disk_changed") } return (bytes, stored) } guard errno == ENOENT else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } // An absent sidecar cannot confer project or artifact provenance. // Only an exact UUID+SHA receipt may recover the old owned bytes. if fstatat(parent, id + ".json", &info, AT_SYMLINK_NOFOLLOW) == 0 { throw failure("unrecognized_retained_disk_metadata") } guard errno == ENOENT else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } guard mediaKey == "primary" else { throw failure("retained_disk_provenance_mismatch") } let bytes = try read(parent, id + ".dsk", maximum: maximumDiskBytes) guard CMOCProject.sha256(bytes) == expectedSHA256 else { throw failure("retained_disk_changed") } let legacy = Record(version: 0, id: id, runID: id, diskSHA256: expectedSHA256, provenance: Provenance(projectKey: nil, artifactID: nil, artifactDiskSHA256: nil, origin: "legacy_receipt"), createdAt: nil, byteCount: bytes.count) return (bytes, legacy) }.value } static func save(directory: URL, runID suppliedID: String, data: Data, provenance: Provenance, recordID: String? = nil) async throws -> Record { let runID = try identifier(suppliedID) let id = try identifier(recordID ?? suppliedID) try validate(provenance) guard !data.isEmpty, data.count <= maximumDiskBytes else { throw failure("invalid_retained_disk_size") } let frozen = Data(data), hash = CMOCProject.sha256(data) return try await Task.detached { let (parent, _) = try directoryFD(directory, create: true) defer { close(parent) } var existing = stat() if fstatat(parent, id, &existing, AT_SYMLINK_NOFOLLOW) == 0 { let child = try childFD(parent, id); defer { close(child) } let stored = try record(child, id: id) guard stored.runID == runID, stored.diskSHA256 == hash, stored.provenance == provenance, try read(child, "disk.dsk", maximum: maximumDiskBytes) == frozen else { throw failure("playtest_disk_exists") } guard fsync(parent) == 0 else { throw failure("playtest_disk_commit_failed") } return stored } guard errno == ENOENT else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } if fstatat(parent, id + ".dsk", &existing, AT_SYMLINK_NOFOLLOW) == 0 { throw failure("playtest_disk_exists") } guard errno == ENOENT else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } let pending = "." + UUID().uuidString + ".pending" guard mkdirat(parent, pending, 0o700) == 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } let stage = try childFD(parent, pending) var published = false defer { if !published { unlinkat(stage, "disk.dsk", 0); unlinkat(stage, "record.json", 0) } close(stage) if !published { unlinkat(parent, pending, AT_REMOVEDIR) } } let stored = Record(version: recordID == nil ? 1 : 2, id: id, runID: runID, diskSHA256: hash, provenance: provenance, createdAt: Date(), byteCount: frozen.count) let encoder = JSONEncoder(); encoder.dateEncodingStrategy = .iso8601; encoder.outputFormatting = [.sortedKeys] let metadata = try encoder.encode(stored) guard metadata.count <= maximumSidecarBytes else { throw failure("invalid_playtest_disk_provenance") } func write(_ name: String, _ bytes: Data) throws { let fd = openat(stage, name, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC, 0o600) guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) } defer { close(fd) } try bytes.withUnsafeBytes { raw in var offset = 0 while offset < raw.count { let written = Darwin.write(fd, raw.baseAddress!.advanced(by: offset), raw.count - offset) if written < 0, errno == EINTR { continue } guard written > 0 else { throw POSIXError(.EIO) } offset += written } } guard fsync(fd) == 0 else { throw POSIXError(.EIO) } } try write("disk.dsk", frozen); try write("record.json", metadata) guard fsync(stage) == 0, renameatx_np(parent, pending, parent, id, UInt32(RENAME_EXCL)) == 0 else { throw failure("playtest_disk_commit_failed") } published = true guard fsync(parent) == 0 else { throw failure("playtest_disk_commit_failed") } return stored }.value } static func diskURL(directory: URL, id: String) throws -> URL { try canonicalDirectory(directory).appendingPathComponent(identifier(id), isDirectory: true).appendingPathComponent("disk.dsk") } } /// One reviewed disk product. IDs bind the selection to this exact artifact; /// keys bind retained copies to the same declared product across compatible builds. struct MCPPlaytestMedium: Sendable { let id: String let name: String let key: String let baseSHA256: String let data: Data let provenance: MCPPlaytestDiskStore.Provenance static func identifier(artifactID: String, key: String) -> String { CMOCProject.sha256(Data((artifactID + "\0" + key).utf8)) } } /// One approved artifact, one private worker process, bounded private media copies. /// The worker's retained emulator globals never share the user's live machine. @MainActor final class MCPPlaytest { static let mutationRequestLimit = 1024 static let audioFieldLimit = 120 static let audioCaptureLimit = 16 static let audioByteLimit = 4 * 1024 * 1024 static let videoFieldLimit = 3600 static let videoClipLimit = 4 static let videoByteLimit = 64 * 1024 * 1024 static let videoRetainedByteLimit = 256 * 1024 * 1024 private static let maximumAudioClipBytes = 44 + 131_072 * 4 let runID: String let projectID: String let revision: Int let artifactID: String let processor: MCPPlaytestProcessor private(set) var startReceipt: [String: Any] = [:] private(set) var retainedDiskURL: URL? private(set) var retainedDiskRecord: MCPPlaytestDiskStore.Record? private(set) var retentionError: String? private(set) var finalReceipt: [String: Any]? private let worker: Worker private let retentionDirectory: URL private let diskProvenance: MCPPlaytestDiskStore.Provenance private let resumedDiskID: String? private var exportedDisk: Data? private var exportedStatus: [String: Any]? private var persistenceTask: Task<[String: Any], Error>? private static var pendingRetentions: [String: MCPPlaytest] = [:] private var cleanupTask: Task? private var valid = true private var busy = false private var finished = false private var accepted: [String: (Data, [String: Any])] = [:] private var mutationRequestsAccepted = 0 private var audioCapturesAccepted = 0 private var audioBytesRetained = 0 private var stopRequestID: String? private var videoDirectories: [String: URL] = [:] private var completedVideos: [String: [String: Any]] = [:] private var videoBytesRetained = 0 private var currentVideoID: String? private var videoIsRecording = false private var videoStopRequestIDs: [String: String] = [:] private struct VideoFileIdentity: Equatable, Sendable { let device: UInt64, inode: UInt64 let size: Int let seconds: Int64, nanos: Int64 init(_ info: stat) { device = UInt64(info.st_dev); inode = UInt64(info.st_ino); size = Int(info.st_size) seconds = Int64(info.st_mtimespec.tv_sec); nanos = Int64(info.st_mtimespec.tv_nsec) } } private var videoFileIdentities: [String: VideoFileIdentity] = [:] private let videoArtifactWillVerify: (@Sendable (URL) throws -> Void)? private func retainVideoMetadata(_ result: [String: Any]) async throws { guard let metadata = (result["video"] ?? result["video_recording"]) as? [String: Any] else { return } videoIsRecording = metadata["status"] as? String == "recording" guard metadata["completed"] as? Bool == true else { return } guard let id = metadata["clip_id"] as? String, let directory = videoDirectories[id] else { throw Self.failure("invalid_playtest_video") } if completedVideos[id] != nil { return } let url = directory.appendingPathComponent("Clip.mp4") let expectedCount = (metadata["byte_count"] as? NSNumber)?.intValue let expectedHash = metadata["sha256"] as? String let willVerify = videoArtifactWillVerify let identity = try await Task.detached { try willVerify?(url) let fd = open(url.path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC | O_NONBLOCK) guard fd >= 0 else { throw Self.failure("invalid_playtest_video") } let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true) defer { try? handle.close() } var info = stat() guard fstat(fd, &info) == 0, info.st_mode & S_IFMT == S_IFREG, (1...Self.videoByteLimit).contains(Int(info.st_size)), Int(info.st_size) == expectedCount else { throw Self.failure("invalid_playtest_video") } let identity = VideoFileIdentity(info) let bytes = try handle.read(upToCount: identity.size + 1) ?? Data() guard bytes.count == identity.size, CMOCProject.sha256(bytes) == expectedHash, fstat(fd, &info) == 0, VideoFileIdentity(info) == identity else { throw Self.failure("invalid_playtest_video") } return identity }.value guard let count = expectedCount, videoBytesRetained <= Self.videoRetainedByteLimit - count else { throw Self.failure("playtest_video_retention_limit") } videoBytesRetained += count; completedVideos[id] = metadata; videoFileIdentities[id] = identity } private func readVideo(_ arguments: [String: Any]) async throws -> [String: Any] { guard Set(arguments.keys).isSubset(of: ["run_id", "clip_id", "offset", "limit"]), let id = arguments["clip_id"] as? String, let metadata = completedVideos[id], let directory = videoDirectories[id], let total = (metadata["byte_count"] as? NSNumber)?.intValue, let identity = videoFileIdentities[id] else { throw Self.failure("playtest_video_unavailable") } func integer(_ value: Any?, fallback: Int, range: ClosedRange) throws -> Int { guard let value else { return fallback } guard let number = value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID(), number.doubleValue.isFinite, number.doubleValue == Double(number.intValue), range.contains(number.intValue) else { throw Self.failure("invalid_arguments") } return number.intValue } let offset = try integer(arguments["offset"], fallback: 0, range: 0...total) let limit = try integer(arguments["limit"], fallback: 65536, range: 1...65536) let url = directory.appendingPathComponent("Clip.mp4") let data = try await Task.detached { let fd = open(url.path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC | O_NONBLOCK) guard fd >= 0 else { throw Self.failure("invalid_playtest_video") } let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true) defer { try? handle.close() } var info = stat() guard fstat(fd, &info) == 0, info.st_mode & S_IFMT == S_IFREG, VideoFileIdentity(info) == identity else { throw Self.failure("invalid_playtest_video") } try handle.seek(toOffset: UInt64(offset)) let count = min(limit, total - offset) let bytes = try handle.read(upToCount: count) ?? Data() guard bytes.count == count, fstat(fd, &info) == 0, VideoFileIdentity(info) == identity else { throw Self.failure("invalid_playtest_video") } return bytes }.value guard valid else { throw Self.failure("stale_run") } var result = metadata result["video_chunk_base64"] = data.base64EncodedString(); result["offset"] = offset result["next_offset"] = offset + data.count; result["eof"] = offset + data.count == total return scoped(result) } private struct MediumState { let source: MCPPlaytestMedium var data: Data var dirty = false var retained: MCPPlaytestDiskStore.Record? var pendingRecordID: String? } private var media: [String: MediumState]? private var mediaOrder: [String] = [] private var mountedMediaID: String? private var mediaExchangeTask: Task<[String: Any], Error>? private var mediaFailures: [String: (Data, String)] = [:] private var mediaCommitPending = false private var pendingMediaSelection: String? private var lastSafeMediaExport: [String: Any]? private init(worker: Worker, projectID: String, revision: Int, artifactID: String, retentionDirectory: URL, diskProvenance: MCPPlaytestDiskStore.Provenance, resumedDiskID: String?, runID: String, processor: MCPPlaytestProcessor, media: [MCPPlaytestMedium]?, videoArtifactWillVerify: (@Sendable (URL) throws -> Void)?) { self.runID = runID self.worker = worker; self.projectID = projectID; self.revision = revision; self.artifactID = artifactID self.retentionDirectory = retentionDirectory; self.diskProvenance = diskProvenance; self.resumedDiskID = resumedDiskID self.processor = processor self.videoArtifactWillVerify = videoArtifactWillVerify if let media { self.media = Dictionary(uniqueKeysWithValues: media.map { ($0.id, MediumState(source: $0, data: $0.data)) }) self.mediaOrder = media.map(\.id); self.mountedMediaID = media.first?.id } } static func start(systemROM: Data, diskROM: Data, disk: Data, bootCommands: String, projectID: String, revision: Int, artifactID: String, modules: [[String: Any]] = [], stopAt: UInt16? = nil, stopModule: String? = nil, flatGuards: [[String: Any]] = [], cpu: String = "6809", helperURL: URL? = nil, retentionDirectory: URL? = nil, diskProvenance: MCPPlaytestDiskStore.Provenance? = nil, resumedDiskID: String? = nil, graphicsBuffers: [[String: Any]] = [], runID: String = UUID().uuidString, media: [MCPPlaytestMedium]? = nil, videoArtifactWillVerify: (@Sendable (URL) throws -> Void)? = nil) async throws -> MCPPlaytest { guard let reservedID = UUID(uuidString: runID) else { throw failure("invalid_playtest_run_id") } guard systemROM.count == 32768, diskROM.count == 8192, !disk.isEmpty, disk.count <= 512 * 1024, ["6809", "6309"].contains(cpu), bootCommands.utf8.count <= 256 else { throw failure("invalid_playtest_artifact") } for pending in Array(pendingRetentions.values) { try? await pending.retainForReplacement() } guard pendingRetentions.isEmpty else { throw failure("playtest_retention_recovery_required") } let provenance = diskProvenance ?? MCPPlaytestDiskStore.Provenance(projectKey: CMOCProject.sha256(Data(projectID.utf8)), artifactID: artifactID, artifactDiskSHA256: CMOCProject.sha256(disk)) try MCPPlaytestDiskStore.validate(provenance) guard provenance.artifactID == artifactID else { throw failure("invalid_playtest_disk_provenance") } if let resumedDiskID { guard diskProvenance != nil, let parent = UUID(uuidString: resumedDiskID), let recorded = provenance.parentDiskID.flatMap(UUID.init(uuidString:)), parent == recorded else { throw failure("invalid_retained_disk_receipt") } } else { guard provenance.parentDiskID == nil, provenance.origin == "verified_artifact", provenance.artifactDiskSHA256 == CMOCProject.sha256(disk) else { throw failure("invalid_playtest_disk_provenance") } } if let media { guard (1...9).contains(media.count), media.first?.key == "primary", media.first?.data == disk, media.first?.provenance == provenance, Set(media.map(\.id)).count == media.count, Set(media.map(\.key)).count == media.count else { throw failure("invalid_playtest_media") } for item in media { try MCPPlaytestDiskStore.validate(item.provenance) guard item.id == MCPPlaytestMedium.identifier(artifactID: artifactID, key: item.key), item.provenance.artifactID == artifactID, item.provenance.projectKey == provenance.projectKey, item.provenance.artifactDiskSHA256 == provenance.artifactDiskSHA256, item.provenance.mediaKey == item.key, item.provenance.mediaBaseSHA256 == item.baseSHA256, !item.data.isEmpty, item.data.count <= 512 * 1024, item.provenance.parentDiskID != nil || CMOCProject.sha256(item.data) == item.baseSHA256 else { throw failure("invalid_playtest_media") } } } let paste = try CocoPaste(bootCommands, mode: .text) guard paste.chords.count <= 256 else { throw failure("invalid_playtest_boot") } let helper = helperURL ?? Bundle.main.bundleURL.appendingPathComponent("Contents/Helpers/vcc-playtest") let worker = try Worker(helper: helper) let test = MCPPlaytest(worker: worker, projectID: projectID, revision: revision, artifactID: artifactID, retentionDirectory: retentionDirectory ?? AppIdentity.supportDirectory.appendingPathComponent("Development Runs/Assistant Playtests"), diskProvenance: provenance, resumedDiskID: resumedDiskID.map { UUID(uuidString: $0)!.uuidString }, runID: reservedID.uuidString, processor: cpu == "6309" ? .hd6309 : .mc6809, media: media, videoArtifactWillVerify: videoArtifactWillVerify) var setup: [String: Any] = ["op": "init", "system_rom": systemROM.base64EncodedString(), "disk_rom": diskROM.base64EncodedString(), "disk": disk.base64EncodedString(), "boot_keys": paste.chords.map { NSNumber(value: $0) }, "modules": modules, "cpu": cpu, "graphics_buffers": graphicsBuffers, "flat_guards": flatGuards] if let media { setup["media_id"] = media[0].id } if let stopAt { guard (modules.isEmpty && !flatGuards.isEmpty && stopModule == nil) || (!modules.isEmpty && flatGuards.isEmpty && stopModule != nil) else { await test.invalidate().value; throw failure("unverified_stop_module") } setup["stop_at"] = Int(stopAt) if let stopModule { setup["stop_module"] = stopModule } } do { let result = try await worker.request(setup) guard result["cpu"] as? String == cpu, result["processor"] as? String == test.processor.rawValue else { throw failure("playtest_processor_mismatch") } test.startReceipt = test.scoped(result) return test } catch { await test.invalidate().value throw error } } @discardableResult func invalidate() -> Task { if let cleanupTask { return cleanupTask } valid = false let cleanup = Task { [self] in do { _ = try await persistStoppedDisk() } catch { retentionError = error.localizedDescription // Revoked access stays revoked. Keep the exported immutable // bytes alive for a retry instead of discarding a saved disk. if exportedDisk != nil { Self.pendingRetentions[runID] = self } else { worker.close() } } if finished { worker.close() } } cleanupTask = cleanup return cleanup } /// Replacement is allowed only after durable retention. A failed write /// leaves the exported disk in memory; retry never sends a second STOP. func retainForReplacement() async throws { guard !busy else { throw Self.failure("playtest_busy") } busy = true; defer { busy = false } _ = try await persistStoppedDisk() } private func persistStoppedDisk() async throws -> [String: Any] { if finished, let finalReceipt { return finalReceipt } if let persistenceTask { return try await persistenceTask.value } let task = Task { try await performDiskPersistence() } persistenceTask = task do { let result = try await task.value persistenceTask = nil return result } catch { persistenceTask = nil throw error } } private func performDiskPersistence() async throws -> [String: Any] { if finished, let finalReceipt { return finalReceipt } if media != nil { return try await performMediaPersistence() } if exportedDisk == nil { var result = try await worker.request(["op": "stop"]) guard let encoded = result.removeValue(forKey: "disk_base64") as? String, let data = Data(base64Encoded: encoded), !data.isEmpty, data.count <= 512 * 1024 else { throw Self.failure("playtest_disk_export_failed") } exportedDisk = Data(data); exportedStatus = result // Video is an independent artifact. A missing or corrupt movie may // never prevent retention of the guest's writable disk bytes. do { try await retainVideoMetadata(result) } catch { exportedStatus?["video_retention_error"] = "The video artifact could not be verified; disk retention continues." } } guard let data = exportedDisk else { throw Self.failure("playtest_disk_export_failed") } do { let record = try await MCPPlaytestDiskStore.save(directory: retentionDirectory, runID: runID, data: data, provenance: diskProvenance) retainedDiskRecord = record retainedDiskURL = try MCPPlaytestDiskStore.diskURL(directory: retentionDirectory, id: record.id) var result = exportedStatus ?? [:] result["disk_retained"] = true; result["retained_disk_id"] = record.id result["retained_disk_sha256"] = record.diskSHA256; result["retained_disk"] = record.publicFields result["status"] = "stopped" finished = true; retentionError = nil; worker.close() let receipt = scoped(result) finalReceipt = receipt; exportedDisk = nil; exportedStatus = nil Self.pendingRetentions.removeValue(forKey: runID) return receipt } catch { retentionError = error.localizedDescription Self.pendingRetentions[runID] = self throw error } } private func mediaFields(status: [String: Any]) -> [String: Any] { var fields = status let actualID = status["media_id"] == nil ? mountedMediaID : status["media_id"] as? String let present = status["disk_present"] as? Bool ?? (mountedMediaID != nil) fields["drive"] = "FD0" fields["media"] = mediaOrder.compactMap { id -> [String: Any]? in guard let item = media?[id] else { return nil } let mounted = present && actualID == id let hash = mounted ? status["disk_sha256"] as? String ?? CMOCProject.sha256(item.data) : CMOCProject.sha256(item.data) var row: [String: Any] = ["media_id": id, "name": item.source.name, "media_key": item.source.key, "base_sha256": item.source.baseSHA256, "media_sha256": hash, "byte_count": item.data.count, "inserted": mounted, "dirty": mounted ? status["disk_dirty"] as? Bool ?? item.dirty : item.dirty, "modified_from_artifact": hash != item.source.baseSHA256, "retained": item.retained?.diskSHA256 == hash] if let record = item.retained { row["retained_disk"] = record.publicFields } if let parent = item.source.provenance.parentDiskID { row["resumed_from_disk_id"] = parent } return row } return fields } /// Only called with a bounded, complete export from the app-owned helper. /// Keep these bytes even if the lease was revoked while the pipe was read. private func receiveMediaExport(_ status: [String: Any]) throws { guard media != nil, let present = status["disk_present"] as? Bool else { throw Self.failure("invalid_playtest_media_reply") } if !present { guard (mountedMediaID == nil || (mediaCommitPending && pendingMediaSelection == nil)), status["disk_base64"] == nil, (status["disk_sha256"] as? String) == "" else { throw Self.failure("invalid_playtest_media_reply") } mountedMediaID = nil return } guard let id = status["media_id"] as? String, id == mountedMediaID || (mediaCommitPending && id == pendingMediaSelection), var item = media?[id], let encoded = status["disk_base64"] as? String, let bytes = Data(base64Encoded: encoded), !bytes.isEmpty, bytes.count <= 512 * 1024, CMOCProject.sha256(bytes) == status["disk_sha256"] as? String else { throw Self.failure("invalid_playtest_media_reply") } if item.data != bytes { item.pendingRecordID = nil } item.data = bytes; item.dirty = status["disk_dirty"] as? Bool ?? false media?[id] = item; mountedMediaID = id } private func retainMedium(_ id: String) async throws -> MCPPlaytestDiskStore.Record { guard var item = media?[id] else { throw Self.failure("invalid_playtest_media_selection") } let hash = CMOCProject.sha256(item.data) if let existing = item.retained, existing.diskSHA256 == hash { return existing } let recordID = item.pendingRecordID ?? UUID().uuidString item.pendingRecordID = recordID; media?[id] = item let stored = try await MCPPlaytestDiskStore.save(directory: retentionDirectory, runID: runID, data: item.data, provenance: item.source.provenance, recordID: recordID) // The paused worker and serialized owner cannot change this medium // during the off-main-thread durable write. guard var current = media?[id], current.data == item.data else { throw Self.failure("playtest_media_changed") } current.retained = stored; current.pendingRecordID = nil; media?[id] = current return stored } private func exchangeMedia(_ selected: String?, expectedSHA: String?, isCurrent: (() -> Bool)?) async throws -> [String: Any] { guard valid, isCurrent?() != false else { throw Self.failure("stale_run") } let before = try await worker.request(["op": "export_media"]) let expectedOldID = mountedMediaID try receiveMediaExport(before) guard mountedMediaID == expectedOldID, valid, isCurrent?() != false, let generation = before["media_generation"] as? NSNumber, let oldHash = before["disk_sha256"] as? String else { throw Self.failure("stale_playtest_media") } if let selected { guard let item = media?[selected], expectedSHA == CMOCProject.sha256(item.data) else { throw Self.failure("playtest_media_hash_mismatch") } } var old: [String: Any] = ["media_id": expectedOldID as Any? ?? NSNull(), "media_sha256": oldHash, "dirty": before["disk_dirty"] as? Bool ?? false, "retained": false] if let expectedOldID { let retained = try await retainMedium(expectedOldID) old["retained"] = true; old["retained_disk"] = retained.publicFields } // Retention can yield to a project edit, rebuild or revocation. Never // commit a disk exchange after that ownership/evidence boundary changes. guard valid, isCurrent?() != false else { throw Self.failure("stale_run") } var request: [String: Any] = ["op": "exchange_media", "expected_media_generation": generation, "expected_disk_sha256": oldHash] if let selected, let item = media?[selected] { request["media_id"] = selected; request["disk_base64"] = item.data.base64EncodedString() } lastSafeMediaExport = before mediaCommitPending = true; pendingMediaSelection = selected let after: [String: Any] do { after = try await worker.request(request) } catch let error as WorkerRejection { mediaCommitPending = false; pendingMediaSelection = nil; throw error } // Commit is already complete. Record the mounted identity before a // possible late revocation so cleanup exports the actual served copy. mountedMediaID = selected; mediaCommitPending = false; pendingMediaSelection = nil let selectedSHA = selected.flatMap { media?[$0] }.map { CMOCProject.sha256($0.data) } ?? "" guard after["disk_sha256"] as? String == selectedSHA, after["previous_disk_sha256"] as? String == oldHash, after["media_id"] as? String == selected, (after["disk_present"] as? Bool) == (selected != nil), (after["media_generation"] as? NSNumber)?.intValue == generation.intValue + 1 else { throw WorkerTransportFailure(reason: "invalid_playtest_media_reply") } for key in ["field_clock", "cycles", "generation", "boot", "pc"] { guard let prior = before[key] as? NSNumber, let current = after[key] as? NSNumber, prior == current else { throw WorkerTransportFailure(reason: "playtest_media_advanced_guest") } } var result = mediaFields(status: after) result["previous_media"] = old result["exchange"] = selected == nil ? "ejected" : "inserted" result["guest_advanced"] = false; result["guest_reset"] = false return result } private func performMediaPersistence() async throws -> [String: Any] { if let pending = mediaExchangeTask { _ = await pending.result } if finished, let finalReceipt { return finalReceipt } if exportedDisk == nil { var result: [String: Any] do { result = try await worker.request(["op": "stop"]) try receiveMediaExport(result) do { try await retainVideoMetadata(result) } catch { result["video_retention_error"] = "The video artifact could not be verified; disk retention continues." } } catch let error as WorkerTransportFailure { // A failed swap pipe cannot have advanced a paused guest. // Every candidate copy is already frozen in the host; retain // those bytes while reporting the unknown final selection. guard let frozen = lastSafeMediaExport else { throw error } result = frozen; result["media_selection_uncertain"] = true result["media_id"] = NSNull(); result["disk_present"] = false result["disk_sha256"] = NSNull(); result["media_generation"] = NSNull() mountedMediaID = nil } mediaCommitPending = false; pendingMediaSelection = nil result.removeValue(forKey: "disk_base64") exportedStatus = result // A nonempty frozen primary also marks an ejected-drive stop as // retryable retention, without issuing a second STOP on failure. guard let primary = mediaOrder.first, let bytes = media?[primary]?.data else { throw Self.failure("invalid_playtest_media") } exportedDisk = bytes } do { var retained: [[String: Any]] = [] for id in mediaOrder { let record = try await retainMedium(id) var fields = record.publicFields; fields["media_id"] = id fields["name"] = media?[id]?.source.name retained.append(fields) } guard let primary = mediaOrder.first, let record = media?[primary]?.retained else { throw Self.failure("playtest_disk_export_failed") } retainedDiskRecord = record; retainedDiskURL = try MCPPlaytestDiskStore.diskURL(directory: retentionDirectory, id: record.id) var result = mediaFields(status: exportedStatus ?? [:]) result["disk_retained"] = true; result["retained_disk_id"] = record.id result["retained_disk_sha256"] = record.diskSHA256; result["retained_disk"] = record.publicFields result["retained_media"] = retained; result["status"] = "stopped" finished = true; retentionError = nil; worker.close() let receipt = scoped(result); finalReceipt = receipt exportedDisk = nil; exportedStatus = nil; Self.pendingRetentions.removeValue(forKey: runID) return receipt } catch { retentionError = error.localizedDescription; Self.pendingRetentions[runID] = self throw error } } /// The host rechecks project/revision/artifact identity before dispatching. /// Cached write receipts are still bound to this live lease, never replayed. func reply(_ tool: String, arguments: [String: Any], isCurrent: (() -> Bool)? = nil) async throws -> [String: Any] { guard valid, arguments["run_id"] as? String == runID else { throw Self.failure("stale_run") } guard !busy else { throw Self.failure("playtest_busy") } busy = true defer { busy = false } if tool == "list_playtest_media" { guard arguments.count == 1, media != nil else { throw Self.failure("invalid_arguments") } if finished, let finalReceipt { return finalReceipt } if exportedDisk != nil { return scoped(mediaFields(status: exportedStatus ?? [:])) } let status = try await worker.request(["op": "media_status"]) guard valid else { throw Self.failure("stale_run") } return scoped(mediaFields(status: status)) } if tool == "capture_playtest_graphics" { guard !finished, exportedDisk == nil, Set(arguments.keys).isSubset(of: ["run_id", "buffer_id"]), (1...2).contains(arguments.count) else { throw Self.failure("invalid_arguments") } var request: [String: Any] = ["op": "graphics_capture"] if let value = arguments["buffer_id"] { guard let id = value as? String, (1...64).contains(id.utf8.count), id.utf8.allSatisfy({ (65...90).contains($0) || (97...122).contains($0) || (48...57).contains($0) || $0 == 95 || $0 == 45 }) else { throw Self.failure("invalid_buffer_id") } request["buffer_id"] = id } let result = try await worker.request(request) guard valid else { throw Self.failure("stale_run") } return scoped(result) } if tool == "capture_playtest" { guard arguments.count == 1 else { throw Self.failure("invalid_arguments") } if finished, let finalReceipt { return finalReceipt } if exportedDisk != nil { return scoped(["status": "retention_pending", "disk_retained": false]) } let result = try await worker.request(["op": "capture"]) guard valid else { throw Self.failure("stale_run") } try await retainVideoMetadata(result) return scoped(result) } if tool == "get_playtest_input" { guard arguments.count == 1, !finished, exportedDisk == nil else { throw Self.failure("invalid_arguments") } let result = try await worker.request(["op": "input_status"]) guard valid else { throw Self.failure("stale_run") } return scoped(result) } if tool == "read_playtest_video" { return try await readVideo(arguments) } guard let requestID = arguments["request_id"] as? String, (1...64).contains(requestID.utf8.count), ["playtest_input", "restart_playtest", "stop_playtest", "playtest_debug", "capture_playtest_audio", "exchange_playtest_media", "start_playtest_video", "stop_playtest_video"].contains(tool) else { throw Self.failure("invalid_arguments") } let signature = try JSONSerialization.data(withJSONObject: ["tool": tool, "arguments": arguments], options: [.sortedKeys]) if let (prior, reason) = mediaFailures[requestID] { guard signature == prior else { throw Self.failure("request_conflict") } throw Self.failure(reason) } if let (prior, receipt) = accepted[requestID] { guard signature == prior else { throw Self.failure("request_conflict") } if tool != "stop_playtest" || receipt["status"] as? String != "retention_pending" { return receipt } } if tool == "stop_playtest", let stopRequestID, requestID != stopRequestID { throw Self.failure("request_conflict: retry the original stop request_id") } if tool == "stop_playtest_video", let clip = currentVideoID, let prior = videoStopRequestIDs[clip], prior != requestID { throw Self.failure("request_conflict: retry the original video stop request_id") } guard exportedDisk == nil || tool == "stop_playtest" else { throw Self.failure("playtest_retention_pending") } guard !finished else { throw Self.failure("stale_run") } // Cleanup has its own single cached receipt and must remain possible // after any execution/audio budget is exhausted. guard ["stop_playtest", "stop_playtest_video"].contains(tool) || mutationRequestsAccepted < Self.mutationRequestLimit || accepted[requestID] != nil else { throw Self.failure("playtest_request_limit") } if tool == "exchange_playtest_media" { guard media != nil, let action = arguments["action"] as? String, ["insert", "eject"].contains(action), Set(arguments.keys) == (action == "insert" ? ["run_id", "request_id", "action", "media_id", "media_sha256"] : ["run_id", "request_id", "action"]) else { throw Self.failure("invalid_arguments") } let selected: String? if action == "insert" { guard let id = arguments["media_id"] as? String, media?[id] != nil, let hash = arguments["media_sha256"] as? String, hash.utf8.count == 64, hash.utf8.allSatisfy({ (48...57).contains($0) || (97...102).contains($0) }) else { throw Self.failure("invalid_playtest_media_selection") } selected = id } else { selected = nil } mutationRequestsAccepted += 1 accepted[requestID] = (signature, scoped(["request_id": requestID, "status": "interrupted"])) let exchange = Task { try await self.exchangeMedia(selected, expectedSHA: arguments["media_sha256"] as? String, isCurrent: isCurrent) } mediaExchangeTask = exchange defer { mediaExchangeTask = nil } var result: [String: Any] do { result = try await exchange.value } catch let error as WorkerRejection { accepted.removeValue(forKey: requestID); mediaFailures[requestID] = (signature, error.reason) throw Self.failure(error.reason) } catch let error as WorkerTransportFailure { invalidate(); throw error } catch { // Validation/retention failures occur before the guarded commit. accepted.removeValue(forKey: requestID); mediaFailures[requestID] = (signature, error.localizedDescription) throw error } // The worker has acknowledged a committed exchange. Keep that // outcome even if authority expired before the reply can be sent; // a late stale lease is not a precommit validation failure. result["request_id"] = requestID let receipt = scoped(result); accepted[requestID] = (signature, receipt) guard valid, isCurrent?() != false else { throw Self.failure("stale_run_after_commit") } return receipt } var request: [String: Any] switch tool { case "start_playtest_video": guard Set(arguments.keys).isSubset(of: ["run_id", "request_id", "include_audio", "max_fields"]) else { throw Self.failure("invalid_arguments") } guard !videoIsRecording else { throw Self.failure("playtest_video_active") } let includeAudio: Bool if let value = arguments["include_audio"] { guard let number = value as? NSNumber, CFGetTypeID(number) == CFBooleanGetTypeID() else { throw Self.failure("invalid_arguments") } includeAudio = number.boolValue } else { includeAudio = true } let maximum: Int if let value = arguments["max_fields"] { guard let number = value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID(), number.doubleValue.isFinite, number.doubleValue == Double(number.intValue), (1...Self.videoFieldLimit).contains(number.intValue) else { throw Self.failure("invalid_arguments") } maximum = number.intValue } else { maximum = 1800 } guard videoDirectories.count < Self.videoClipLimit, videoBytesRetained <= Self.videoRetainedByteLimit - Self.videoByteLimit else { throw Self.failure("playtest_video_capture_limit") } let id = UUID().uuidString let directory = retentionDirectory.appendingPathComponent("Videos", isDirectory: true).appendingPathComponent(runID, isDirectory: true).appendingPathComponent(id, isDirectory: true) try await Task.detached { try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700]) }.value videoDirectories[id] = directory; currentVideoID = id request = ["op": "video_start", "clip_id": id, "directory": directory.path, "include_audio": includeAudio, "max_fields": maximum] case "stop_playtest_video": guard arguments.count == 2, currentVideoID != nil else { throw Self.failure("playtest_video_unavailable") } request = ["op": "video_stop"] case "capture_playtest_audio": guard arguments.count == 3, let n = arguments["fields"] as? NSNumber, CFGetTypeID(n) != CFBooleanGetTypeID(), n.doubleValue.isFinite, n.doubleValue == Double(n.intValue), (1...Self.audioFieldLimit).contains(n.intValue) else { throw Self.failure("invalid_arguments") } guard audioCapturesAccepted < Self.audioCaptureLimit, audioBytesRetained <= Self.audioByteLimit - Self.maximumAudioClipBytes else { throw Self.failure("playtest_audio_capture_limit") } request = ["op": "audio_capture", "fields": n.intValue] case "playtest_input": guard arguments.count == 3, let steps = arguments["steps"] as? [[String: Any]], (1...64).contains(steps.count) else { throw Self.failure("invalid_arguments") } var plan: [[String: Any]] = [], total = 0 for step in steps { guard Set(step.keys).isSubset(of: ["keys", "fields", "joysticks"]), let keys = step["keys"] as? [String], keys.count <= 8, Set(keys).count == keys.count, let n = step["fields"] as? NSNumber, CFGetTypeID(n) != CFBooleanGetTypeID(), n.doubleValue.isFinite, n.doubleValue == Double(n.intValue), (1...600).contains(n.intValue) else { throw Self.failure("invalid_arguments") } let mask = try keys.reduce(UInt64(0)) { value, key in guard let chord = Self.chord(key) else { throw Self.failure("invalid_playtest_key") } return value | chord } total += n.intValue guard total <= 3600 else { throw Self.failure("playtest_input_limit") } var translated: [String: Any] = ["mask": NSNumber(value: mask), "fields": n.intValue] if let joysticks = step["joysticks"] { translated["joysticks"] = try MCPPlaytestJoystick.snapshots(joysticks) } plan.append(translated) } request = ["op": "input", "steps": plan] case "playtest_debug": guard let action = arguments["action"] as? String else { throw Self.failure("invalid_arguments") } if action == "stop_at" { guard (5...6).contains(arguments.count), Set(arguments.keys).isSubset(of: ["run_id", "request_id", "action", "selection", "module_id", "address"]), arguments["selection"] == nil || arguments["selection"] is String, arguments["module_id"] == nil || ((arguments["module_id"] as? String)?.isEmpty == false), let address = arguments["address"] as? NSNumber, CFGetTypeID(address) != CFBooleanGetTypeID(), address.doubleValue == Double(address.intValue), (0...65535).contains(address.intValue) else { throw Self.failure("invalid_arguments") } request = ["op": "stop_at", "address": address.intValue] if let module = arguments["module_id"] { request["module_id"] = module } } else { guard arguments.count == 3, ["pause", "continue", "step"].contains(action) else { throw Self.failure("invalid_arguments") } request = ["op": action] } case "restart_playtest": guard arguments.count == 2 else { throw Self.failure("invalid_arguments") } guard !videoIsRecording else { throw Self.failure("playtest_video_active: stop the recording before restarting") } request = ["op": "restart"] default: guard arguments.count == 2 else { throw Self.failure("invalid_arguments") } request = ["op": "stop"] } // Reserve the identity before execution. An interrupted operation must // never be retried as a new input sequence with the same request ID. if tool == "stop_playtest" { stopRequestID = requestID } if tool == "stop_playtest_video", let clip = currentVideoID { videoStopRequestIDs[clip] = requestID } if !["stop_playtest", "stop_playtest_video"].contains(tool) { mutationRequestsAccepted += 1 } if tool == "capture_playtest_audio" { audioCapturesAccepted += 1 } accepted[requestID] = (signature, scoped(["request_id": requestID, "status": "interrupted"])) if tool == "stop_playtest" { do { var result = try await persistStoppedDisk() result["request_id"] = requestID finalReceipt = result; accepted[requestID] = (signature, result) return result } catch { if exportedDisk != nil { accepted[requestID] = (signature, scoped(["status": "retention_pending", "disk_retained": false])) } else { invalidate() } throw error } } do { lastSafeMediaExport = nil var result = try await worker.request(request) guard valid else { throw Self.failure("stale_run") } try await retainVideoMetadata(result) if tool == "capture_playtest_audio" { guard let encoded = result["audio_wav_base64"] as? String, let wav = Data(base64Encoded: encoded), (44...Self.maximumAudioClipBytes).contains(wav.count), let metadata = result["audio"] as? [String: Any], metadata["sha256"] as? String == CMOCProject.sha256(wav), (metadata["byte_count"] as? NSNumber)?.intValue == wav.count else { throw Self.failure("invalid_playtest_audio") } audioBytesRetained += wav.count } result["request_id"] = requestID let receipt = scoped(result) accepted[requestID] = (signature, receipt) return receipt } catch { // The worker can have advanced before a broken pipe/timeout. Retire // this run rather than allowing uncertain input to execute twice. invalidate() throw error } } func capture() async throws -> [String: Any] { try await reply("capture_playtest", arguments: ["run_id": runID]) } /// Private app-side immutable snapshot. Raw memory never crosses the grant: /// MCPCMOC applies verified source ranges and named-watch rules first. func debugCapture() async throws -> [String: Any] { try await command(["op": "debug"]) } func continuePlaytest() async throws -> [String: Any] { try await command(["op": "continue"]) } func pausePlaytest() async throws -> [String: Any] { try await command(["op": "pause"]) } func stepPlaytest() async throws -> [String: Any] { try await command(["op": "step"]) } func stopAt(_ address: UInt16, moduleID: String) async throws -> [String: Any] { try await command(["op": "stop_at", "address": Int(address), "module_id": moduleID]) } private func command(_ request: [String: Any]) async throws -> [String: Any] { guard valid, !finished else { throw Self.failure("stale_run") } guard exportedDisk == nil else { throw Self.failure("playtest_retention_pending") } guard !busy else { throw Self.failure("playtest_busy") } busy = true defer { busy = false } if let operation = request["op"] as? String, ["continue", "step", "stop_at"].contains(operation) { lastSafeMediaExport = nil } let result = try await worker.request(request) guard valid else { throw Self.failure("stale_run") } try await retainVideoMetadata(result) return scoped(result) } private func scoped(_ result: [String: Any]) -> [String: Any] { var result = result result["run_id"] = runID; result["project_id"] = projectID result["revision"] = revision; result["artifact_id"] = artifactID result["requested_processor"] = processor.rawValue result["mutation_request_limit"] = Self.mutationRequestLimit result["mutation_requests_used"] = mutationRequestsAccepted result["remaining_mutation_requests"] = max(0, Self.mutationRequestLimit - mutationRequestsAccepted) result["stop_retention_exempt"] = true result["video_stop_retention_exempt"] = true result["video_clip_limit"] = Self.videoClipLimit result["remaining_video_clips"] = max(0, Self.videoClipLimit - videoDirectories.count) result["video_byte_limit"] = Self.videoByteLimit result["video_retained_byte_limit"] = Self.videoRetainedByteLimit result["remaining_video_bytes"] = max(0, Self.videoRetainedByteLimit - videoBytesRetained) result["audio_capture_limit"] = Self.audioCaptureLimit result["remaining_audio_captures"] = max(0, Self.audioCaptureLimit - audioCapturesAccepted) result["audio_byte_limit"] = Self.audioByteLimit result["remaining_audio_bytes"] = max(0, Self.audioByteLimit - audioBytesRetained) result["artifact_disk_sha256"] = diskProvenance.artifactDiskSHA256 as Any? ?? NSNull() result["disk_origin"] = diskProvenance.origin; result["disk_provenance"] = diskProvenance.publicFields if media != nil { result["media_exchange"] = true result["boot_disk_provenance"] = diskProvenance.publicFields if let id = mountedMediaID, let current = media?[id] { result["disk_origin"] = current.source.provenance.origin result["disk_provenance"] = current.source.provenance.publicFields } else { result["disk_origin"] = NSNull(); result["disk_provenance"] = NSNull() } } if let resumedDiskID { result["resumed_from_disk_id"] = resumedDiskID } return result } /// Names identify physical CoCo keys, independently of host keyboard layout. static func chord(_ key: String) -> UInt64? { let special: [String: Int] = ["up": 27, "down": 28, "left": 29, "backspace": 29, "right": 30, "space": 31, "enter": 48, "clear": 49, "break": 50, "alt": 51, "control": 52, "f1": 53, "f2": 54, "shift": 55, "period": 46] if let bit = special[key] { return UInt64(1) << bit } if key.utf8.count == 1, let c = key.utf8.first, (97...122).contains(c) || (48...57).contains(c) { return CocoKeyboard.chord(for: key) } return nil } nonisolated private static func failure(_ value: String) -> ProfileFailure { .message(value) } /// Blocking pipe I/O stays on this dedicated queue. Deadline termination /// also releases the worker's held keys, media and core globals by exit. private struct WorkerTransportFailure: LocalizedError { let reason: String var errorDescription: String? { reason } } private struct WorkerRejection: LocalizedError { let reason: String var errorDescription: String? { reason } } private final class Worker: @unchecked Sendable { private let process = Process() private let input = Pipe(), output = Pipe() private let queue = DispatchQueue(label: "com.brianholman.vccplus.playtest") private var buffered = Data() init(helper: URL) throws { process.executableURL = helper process.arguments = [] process.standardInput = input; process.standardOutput = output _ = fcntl(input.fileHandleForWriting.fileDescriptor, F_SETNOSIGPIPE, 1) process.standardError = FileHandle.nullDevice try process.run() } func close() { if process.isRunning { process.terminate() } } func request(_ request: [String: Any]) async throws -> [String: Any] { let data = try JSONSerialization.data(withJSONObject: request, options: [.sortedKeys]) guard data.count <= 1024 * 1024 else { throw MCPPlaytest.failure("playtest_message_limit") } return try await withCheckedThrowingContinuation { continuation in queue.async { let watchdog = DispatchWorkItem { [self] in close() } DispatchQueue.global().asyncAfter(deadline: .now() + 45, execute: watchdog) defer { watchdog.cancel() } do { guard self.process.isRunning else { throw MCPPlaytest.failure("playtest_worker_unavailable") } try self.input.fileHandleForWriting.write(contentsOf: data + Data([10])) while !self.buffered.contains(10) { // FileHandle.read(upToCount:) can wait to fill its // requested length on a pipe. JSONL replies may be // much shorter while the worker waits for a new // command, so use one POSIX read of available bytes. var chunk = [UInt8](repeating: 0, count: 4096) let count = chunk.withUnsafeMutableBytes { Darwin.read(self.output.fileHandleForReading.fileDescriptor, $0.baseAddress, $0.count) } if count < 0 && errno == EINTR { continue } guard count > 0 else { throw MCPPlaytest.failure("playtest_worker_unavailable") } self.buffered.append(contentsOf: chunk.prefix(count)) guard self.buffered.count <= 1024 * 1024 else { throw MCPPlaytest.failure("playtest_message_limit") } } let end = self.buffered.firstIndex(of: 10)! let line = self.buffered[..