Files
Brian Holman 5534005799 Sync VCC Plus 3.7.1 build 67 source
Refresh reviewed MCP output export, four-drive owned playtests, bounded BASIC readiness, and pinned CMOC 0.1.101 source/patches. Preserve independent source-edition identity, empty libraries, notices and privacy boundaries.

Validated 74 export/privacy checks, pinned dependency sources, and an independent unsigned universal Release build. A subsequent documentation-only correction removes an excluded qualification link; all build inputs remain identical.
2026-11-17 08:42:27 -07:00

1506 lines
92 KiB
Swift

// 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<String>()
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?
let writeProtected: Bool?
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, writeProtected: Bool? = 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; self.writeProtected = writeProtected
}
func protecting(_ enabled: Bool) -> Self {
Self(projectKey: projectKey, artifactID: artifactID, artifactDiskSHA256: artifactDiskSHA256,
parentDiskID: parentDiskID, origin: origin, originArtifactID: originArtifactID,
originArtifactDiskSHA256: originArtifactDiskSHA256, mediaKey: mediaKey,
mediaBaseSHA256: mediaBaseSHA256, writeProtected: enabled)
}
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["write_protected"] = writeProtected ?? false
fields["write_protection_recorded"] = writeProtected != nil
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<Void, Never>?
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<Int>) 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 writeProtected = false
var retained: MCPPlaytestDiskStore.Record?
var pendingRecordID: String?
}
private var media: [String: MediumState]?
private var mediaOrder: [String] = []
private let multiDrive: Bool
private var mountedMediaIDs: [String?] = Array(repeating: nil, count: 4)
private var pendingMediaDrive: Int?
private var lastSafeMediaExports: [Int: [String: Any]] = [:]
private var frozenDriveExports = Set<Int>()
private var mediaFreezeAcknowledged = false
private var mediaStopDrained = false
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]?, multiDrive: Bool,
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.multiDrive = multiDrive
self.videoArtifactWillVerify = videoArtifactWillVerify
if let media {
self.media = Dictionary(uniqueKeysWithValues: media.map { ($0.id, MediumState(source: $0, data: $0.data, writeProtected: $0.provenance.writeProtected ?? false)) })
self.mediaOrder = media.map(\.id); self.mountedMediaID = media.first?.id
self.mountedMediaIDs[0] = 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, multiDrive: Bool = false,
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, multiDrive: multiDrive, 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 protection = provenance.writeProtected { setup["write_protected"] = protection }
if multiDrive {
guard media != nil else { await test.invalidate().value; throw failure("invalid_playtest_media") }
setup["multi_drive"] = true
setup["write_protected"] = media?.first?.provenance.writeProtected ?? false
}
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<Void, Never> {
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 driveRow(_ status: [String: Any], drive: Int) throws -> [String: Any] {
guard let rows = status["drives"] as? [[String: Any]], rows.count == 4,
rows.enumerated().allSatisfy({ index, row in
guard let number = row["drive"] as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() else { return false }
return number.doubleValue == Double(index)
}) else { throw Self.failure("invalid_playtest_media_reply") }
return rows[drive]
}
private func multiMediaFields(status: [String: Any]) -> [String: Any] {
var fields = status
let workerRows = status["drives"] as? [[String: Any]] ?? []
fields["media_contract_version"] = 2
fields["drive"] = "FD0" // Existing top-level compatibility field.
fields["drives"] = (0..<4).map { drive -> [String: Any] in
var row = workerRows.count == 4 ? workerRows[drive] : ["drive": drive, "label": "FD\(drive)", "unavailable": true]
if let id = row["media_id"] as? String, let item = media?[id] {
row["base_sha256"] = item.source.baseSHA256
row["media_sha256"] = row["disk_sha256"]
row["media_key"] = item.source.key
row["name"] = item.source.name
row["provenance"] = item.source.provenance.protecting(row["write_protected"] as? Bool ?? item.writeProtected).publicFields
row["modified_from_artifact"] = row["disk_sha256"] as? String != item.source.baseSHA256
let retained = item.retained
row["retained"] = retained?.diskSHA256 == row["disk_sha256"] as? String && retained?.provenance.writeProtected == row["write_protected"] as? Bool
if let retained { row["retained_disk"] = retained.publicFields }
}
return row
}
fields["media"] = mediaOrder.compactMap { id -> [String: Any]? in
guard let item = media?[id] else { return nil }
let mounted = workerRows.first { $0["media_id"] as? String == id && $0["disk_present"] as? Bool == true }
let hash = mounted?["disk_sha256"] as? String ?? CMOCProject.sha256(item.data)
let protection = mounted?["write_protected"] as? Bool ?? item.writeProtected
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 != nil, "drive": mounted?["drive"] as Any? ?? NSNull(),
"dirty": mounted?["disk_dirty"] as? Bool ?? item.dirty, "write_protected": protection,
"provenance": item.source.provenance.protecting(protection).publicFields,
"modified_from_artifact": hash != item.source.baseSHA256,
"retained": item.retained?.diskSHA256 == hash && item.retained?.provenance.writeProtected == protection]
if let retained = item.retained { row["retained_disk"] = retained.publicFields }
if let parent = item.source.provenance.parentDiskID { row["resumed_from_disk_id"] = parent }
if status["media_selection_uncertain"] as? Bool == true { row["placement_uncertain"] = true }
return row
}
return fields
}
/// One bounded worker message contains one drive's bytes plus a coherent
/// four-drive metadata observation. Never concatenate four disk payloads.
private func receiveMultiMediaExport(_ status: [String: Any], drive: Int) throws {
let row = try driveRow(status, drive: drive)
guard let exported = status["exported_drive"] as? [String: Any], NSDictionary(dictionary: exported).isEqual(to: row),
let present = row["disk_present"] as? Bool, let hash = row["disk_sha256"] as? String,
let protection = row["write_protected"] as? Bool else { throw Self.failure("invalid_playtest_media_reply") }
let id = row["media_id"] as? String
let pendingMatches = mediaCommitPending && pendingMediaDrive == drive && id == pendingMediaSelection
guard id == mountedMediaIDs[drive] || pendingMatches else { throw Self.failure("invalid_playtest_media_reply") }
if !present {
guard id == nil, hash.isEmpty, status["disk_base64"] == nil,
(row["byte_count"] as? NSNumber)?.intValue == 0 else { throw Self.failure("invalid_playtest_media_reply") }
mountedMediaIDs[drive] = nil
} else {
guard let id, var item = media?[id], let encoded = status["disk_base64"] as? String,
let bytes = Data(base64Encoded: encoded), !bytes.isEmpty, bytes.count <= 512 * 1024,
bytes.count == (row["byte_count"] as? NSNumber)?.intValue,
CMOCProject.sha256(bytes) == hash else { throw Self.failure("invalid_playtest_media_reply") }
if item.data != bytes || item.writeProtected != protection { item.pendingRecordID = nil }
item.data = bytes; item.dirty = row["disk_dirty"] as? Bool ?? false; item.writeProtected = protection
media?[id] = item; mountedMediaIDs[drive] = id
}
mountedMediaID = mountedMediaIDs[0]
}
private func exchangeMultiMedia(_ selected: String?, expectedSHA: String?, drive: Int,
writeProtected: Bool?, isCurrent: (() -> Bool)?) async throws -> [String: Any] {
guard valid, isCurrent?() != false else { throw Self.failure("stale_run") }
if let selected {
guard media?[selected] != nil else { throw Self.failure("invalid_playtest_media_selection") }
guard !mountedMediaIDs.enumerated().contains(where: { $0.offset != drive && $0.element == selected }) else {
throw Self.failure("playtest_media_already_inserted")
}
}
var frozen: [Int: [String: Any]] = [:]
for index in 0..<4 {
let snapshot = try await worker.request(["op": "export_media", "drive": index])
try receiveMultiMediaExport(snapshot, drive: index)
if let first = frozen[0] {
for key in ["field_clock", "cycles", "generation", "boot", "pc"] {
guard let a = first[key] as? NSNumber, let b = snapshot[key] as? NSNumber, a == b else {
throw WorkerTransportFailure(reason: "playtest_media_advanced_guest")
}
}
}
frozen[index] = snapshot
}
guard let before = frozen[drive] else { throw Self.failure("invalid_playtest_media_reply") }
let oldRow = try driveRow(before, drive: drive), expectedOldID = mountedMediaIDs[drive]
guard valid, isCurrent?() != false, let generation = oldRow["media_generation"] as? NSNumber,
let oldHash = oldRow["disk_sha256"] as? String else { throw Self.failure("stale_playtest_media") }
if let selected, let item = media?[selected], expectedSHA != CMOCProject.sha256(item.data) {
throw Self.failure("playtest_media_hash_mismatch")
}
var old: [String: Any] = ["media_id": expectedOldID as Any? ?? NSNull(), "media_sha256": oldHash,
"drive": drive, "dirty": oldRow["disk_dirty"] as? Bool ?? false, "retained": false,
"write_protected": oldRow["write_protected"] as? Bool ?? false]
if let expectedOldID {
let retained = try await retainMedium(expectedOldID)
old["retained"] = true; old["retained_disk"] = retained.publicFields
}
guard valid, isCurrent?() != false, mountedMediaIDs[drive] == expectedOldID else { throw Self.failure("stale_run") }
var request: [String: Any] = ["op": "exchange_media", "drive": drive,
"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()
request["write_protected"] = writeProtected ?? item.writeProtected
}
lastSafeMediaExports = frozen
mediaCommitPending = true; pendingMediaDrive = drive; pendingMediaSelection = selected
let after: [String: Any]
do { after = try await worker.request(request) }
catch let error as WorkerRejection { mediaCommitPending = false; pendingMediaDrive = nil; pendingMediaSelection = nil; throw error }
// Acknowledged commit is authoritative even if the grant expires now.
mountedMediaIDs[drive] = selected; mountedMediaID = mountedMediaIDs[0]
mediaCommitPending = false; pendingMediaDrive = nil; pendingMediaSelection = nil
let next = try driveRow(after, drive: drive)
let selectedSHA = selected.flatMap { media?[$0] }.map { CMOCProject.sha256($0.data) } ?? ""
guard next["disk_sha256"] as? String == selectedSHA, next["media_id"] as? String == selected,
next["disk_present"] as? Bool == (selected != nil),
(next["media_generation"] as? NSNumber)?.intValue == generation.intValue + 1,
after["previous_disk_sha256"] as? String == oldHash else { throw WorkerTransportFailure(reason: "invalid_playtest_media_reply") }
if let selected, var item = media?[selected], let effective = next["write_protected"] as? Bool {
if effective != item.writeProtected { item.pendingRecordID = nil }
item.writeProtected = effective; media?[selected] = item
}
for index in 0..<4 where index != drive {
guard NSDictionary(dictionary: try driveRow(before, drive: index)).isEqual(to: try driveRow(after, drive: index)) else {
throw WorkerTransportFailure(reason: "playtest_unrelated_drive_changed")
}
}
for key in ["field_clock", "cycles", "generation", "boot", "pc"] {
guard let a = before[key] as? NSNumber, let b = after[key] as? NSNumber, a == b else { throw WorkerTransportFailure(reason: "playtest_media_advanced_guest") }
}
var result = mediaFields(status: after)
result["target_drive"] = drive; result["previous_media"] = old
result["exchange"] = selected == nil ? "ejected" : "inserted"
result["guest_advanced"] = false; result["guest_reset"] = false
return result
}
private func performMultiMediaPersistence() async throws -> [String: Any] {
if let pending = mediaExchangeTask { _ = await pending.result }
if finished, let finalReceipt { return finalReceipt }
if !mediaFreezeAcknowledged {
do {
var result = try await worker.request(["op": "stop"])
guard result["media_frozen"] as? Bool == true else { throw Self.failure("invalid_playtest_media_reply") }
_ = try driveRow(result, drive: 0)
mediaFreezeAcknowledged = true; exportedStatus = result
guard let primary = mediaOrder.first, let bytes = media?[primary]?.data else { throw Self.failure("invalid_playtest_media") }
exportedDisk = bytes // Retry marker, not a claim that all drives were drained.
do { try await retainVideoMetadata(result) }
catch { result["video_retention_error"] = "The video artifact could not be verified; disk retention continues."; exportedStatus = result }
} catch let error as WorkerTransportFailure {
// Only a fully observed paused four-drive export can recover a
// lost exchange reply. It is never substituted after execution.
guard lastSafeMediaExports.count == 4, let before = lastSafeMediaExports[0] else { throw error }
var result = before
result.removeValue(forKey: "disk_base64"); result.removeValue(forKey: "exported_drive")
result["media_selection_uncertain"] = true
result["uncertain_drives"] = pendingMediaDrive.map { [$0] } ?? Array(0..<4)
if var rows = result["drives"] as? [[String: Any]] {
for index in (pendingMediaDrive.map { [$0] } ?? Array(0..<4)) {
rows[index]["media_id"] = NSNull(); rows[index]["disk_present"] = NSNull()
rows[index]["inserted"] = NSNull(); rows[index]["selection_uncertain"] = true
rows[index]["disk_sha256"] = NSNull(); rows[index]["media_generation"] = NSNull()
mountedMediaIDs[index] = nil
}
result["drives"] = rows
if pendingMediaDrive == nil || pendingMediaDrive == 0 {
result["media_id"] = NSNull(); result["disk_present"] = NSNull(); result["disk_sha256"] = NSNull()
}
}
mountedMediaID = mountedMediaIDs[0]
exportedStatus = result; mediaFreezeAcknowledged = true; mediaStopDrained = true
frozenDriveExports = Set(0..<4)
exportedDisk = mediaOrder.first.flatMap { media?[$0]?.data }
}
}
do {
for drive in 0..<4 where !frozenDriveExports.contains(drive) {
let result = try await worker.request(["op": "export_media", "drive": drive])
try receiveMultiMediaExport(result, drive: drive)
// Each reply must match the STOP observation, with no execution
// or selection change while bounded exports are drained.
guard let frozen = exportedStatus,
NSDictionary(dictionary: try driveRow(frozen, drive: drive)).isEqual(to: try driveRow(result, drive: drive)) else {
throw Self.failure("playtest_frozen_media_changed")
}
frozenDriveExports.insert(drive)
}
if !mediaStopDrained {
do { _ = try await worker.request(["op": "finish_stop"]) }
catch is WorkerTransportFailure { /* Every mounted disk was already drained and verified. */ }
mediaStopDrained = true
}
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
}
}
private func mediaFields(status: [String: Any]) -> [String: Any] {
if multiDrive { return multiMediaFields(status: status) }
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 {
if multiDrive { try receiveMultiMediaExport(status, drive: 0); return }
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,
!multiDrive || existing.provenance.writeProtected == item.writeProtected {
guard let projectKey = existing.provenance.projectKey,
let artifactHash = existing.provenance.artifactDiskSHA256 else { throw Self.failure("invalid_playtest_disk_provenance") }
let loaded = try await MCPPlaytestDiskStore.load(directory: retentionDirectory, id: existing.id,
expectedSHA256: hash, projectKey: projectKey, artifactDiskSHA256: artifactHash,
mediaKey: existing.provenance.mediaKey ?? "primary", mediaBaseSHA256: existing.provenance.mediaBaseSHA256)
guard loaded.record.id == existing.id, loaded.record.runID == existing.runID,
loaded.record.provenance == existing.provenance, loaded.record.diskSHA256 == existing.diskSHA256,
loaded.record.byteCount == existing.byteCount, loaded.data == item.data else { throw Self.failure("retained_disk_changed") }
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: multiDrive ? item.source.provenance.protecting(item.writeProtected) : 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)?,
drive: Int = 0, writeProtected: Bool? = nil) async throws -> [String: Any] {
if multiDrive { return try await exchangeMultiMedia(selected, expectedSHA: expectedSHA, drive: drive, writeProtected: writeProtected, isCurrent: isCurrent) }
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()
if let protection = item.source.provenance.writeProtected { request["write_protected"] = protection }
}
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 multiDrive { return try await performMultiMediaPersistence() }
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] {
var arguments = arguments
if tool == "exchange_playtest_media", multiDrive, arguments["drive"] == nil { arguments["drive"] = 0 }
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) else { throw Self.failure("invalid_arguments") }
var required: Set<String> = action == "insert" ? ["run_id", "request_id", "action", "media_id", "media_sha256"] : ["run_id", "request_id", "action"]
if multiDrive { required.insert("drive") }
let optional: Set<String> = multiDrive && action == "insert" ? ["write_protected"] : []
guard required.isSubset(of: Set(arguments.keys)), Set(arguments.keys).isSubset(of: required.union(optional)) else { throw Self.failure("invalid_arguments") }
let drive: Int
if multiDrive {
guard let value = arguments["drive"] as? NSNumber, CFGetTypeID(value) != CFBooleanGetTypeID(),
value.doubleValue.isFinite, value.doubleValue == Double(value.intValue), (0...3).contains(value.intValue) else { throw Self.failure("invalid_arguments") }
drive = value.intValue
} else { drive = 0 }
let protection: Bool?
if let value = arguments["write_protected"] {
guard let number = value as? NSNumber, CFGetTypeID(number) == CFBooleanGetTypeID() else { throw Self.failure("invalid_arguments") }
protection = number.boolValue
} else { protection = nil }
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, drive: drive, writeProtected: protection) }
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; lastSafeMediaExports.removeAll()
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; lastSafeMediaExports.removeAll() }
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 = multiDrive && media != nil ? mediaFields(status: 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
let currentProtection = (result["drives"] as? [[String: Any]])?.first?["write_protected"] as? Bool ?? current.writeProtected
result["disk_provenance"] = multiDrive ? current.source.provenance.protecting(currentProtection).publicFields : 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[..<end]
self.buffered.removeSubrange(...end)
guard let reply = try JSONSerialization.jsonObject(with: line) as? [String: Any] else {
throw MCPPlaytest.failure("playtest_invalid_reply")
}
if let error = reply["error"] as? String { throw WorkerRejection(reason: error) }
guard let result = reply["result"] as? [String: Any] else { throw MCPPlaytest.failure("playtest_invalid_reply") }
continuation.resume(returning: result)
} catch let error as WorkerRejection {
continuation.resume(throwing: error)
} catch {
continuation.resume(throwing: WorkerTransportFailure(reason: error.localizedDescription))
}
}
}
}
deinit { close() }
}
}