zigmini 1.0.0-beta.3 → 1.1.0-beta.1

package/host/document-reader/Protocol.swift

@@ -0,0 +1,647 @@
+import Foundation
+import CryptoKit
+
+// SIZE_OK: the T3 shared-file freeze requires the entire native wire seam in this file.
+// No selector, document parser, authorization, sandbox, or process supervisor lives here.
+enum HelperProtocolError: String, Error {
+    case invalidJSON = "invalid_json"
+    case invalidShape = "invalid_shape"
+    case invalidOperation = "invalid_operation"
+    case wrongPrivilege = "wrong_privilege"
+    case invalidIdentity = "invalid_identity"
+    case invalidBounds = "invalid_bounds"
+    case invalidBase64 = "invalid_base64"
+    case requestMismatch = "request_mismatch"
+    case terminalState = "terminal_state"
+    case missingTerminal = "missing_terminal"
+    case invalidSequence = "invalid_sequence"
+    case invalidSnapshot = "invalid_snapshot"
+    case invalidCursor = "invalid_cursor"
+}
+
+enum HelperPrivilege: String {
+    case selector, document
+    init(argument: String) throws {
+        guard let value = Self(rawValue: argument) else { throw HelperProtocolError.wrongPrivilege }
+        self = value
+    }
+}
+
+enum HelperLimits {
+    static let originalBytes = 10 * 1024 * 1024
+    static let requestBytes = 13_981_016 + 65_536
+    static let streamBytes = 16 * 1024 * 1024
+    static let frameBytes = 16 * 1024 * 1024
+    static let textBytes = 48 * 1024
+    static let preparedTextBytes = 20 * 1024 * 1024
+    static let imageBytes = 4 * 1024 * 1024
+}
+
+struct NativeIdentity: Codable, Equatable {
+    let device: String
+    let inode: String
+    let size: Int
+    let mtimeNs: String
+    let ctimeNs: String
+    let nlink: Int
+
+    func validate() throws {
+        guard let dev = Int32(device), String(dev) == device,
+              let ino = UInt64(inode), String(ino) == inode,
+              Self.validNanoseconds(mtimeNs), Self.validNanoseconds(ctimeNs),
+              (1...HelperLimits.originalBytes).contains(size), nlink == 1 else {
+            throw HelperProtocolError.invalidIdentity
+        }
+    }
+
+    private static func validNanoseconds(_ value: String) -> Bool {
+        guard HelperCodec.matches(value, #"^(?:0|-?[1-9][0-9]*)$"#) else { return false }
+        let negative = value.hasPrefix("-")
+        let magnitude = negative ? String(value.dropFirst()) : value
+        let maximum = negative ? "9223372036854775808000000000" : "9223372036854775807999999999"
+        return magnitude.count < maximum.count || (magnitude.count == maximum.count && magnitude <= maximum)
+    }
+
+    // time_t * 1e9 must never be computed in Int64 or Double.
+    static func nanoseconds(seconds: Int64, nanoseconds: Int) throws -> String {
+        guard (0..<1_000_000_000).contains(nanoseconds) else { throw HelperProtocolError.invalidIdentity }
+        let negative = seconds < 0
+        let magnitude = seconds.magnitude - (negative && nanoseconds > 0 ? 1 : 0)
+        let fraction = negative && nanoseconds > 0 ? 1_000_000_000 - nanoseconds : nanoseconds
+        let joined = String(magnitude) + String(repeating: "0", count: 9 - String(fraction).count) + String(fraction)
+        let trimmed = joined.drop(while: { $0 == "0" })
+        return trimmed.isEmpty ? "0" : (negative ? "-" : "") + trimmed
+    }
+}
+
+enum SelectorOperation: String, Codable { case list = "selector.list", snapshot = "selector.snapshot" }
+enum SelectorRoot: String, Codable { case home, computer, downloads }
+struct SelectorRequest: Codable {
+    let version: Int
+    let requestId: String
+    let operation: SelectorOperation
+    let root: SelectorRoot
+    let segments: [String]
+    let showHidden: Bool?
+    let query: String?
+    let afterName: String?
+    let expectedIdentity: NativeIdentity?
+}
+
+enum DocumentOperation: String, Codable {
+    case inspect = "document.inspect", text = "document.text", pages = "document.pages", ocr = "document.ocr"
+}
+enum DocumentFormat: String, Codable { case html, md, txt, pdf }
+enum DocumentEncoding: String, Codable {
+    case utf8 = "utf-8", utf16le = "utf-16le", utf16be = "utf-16be", eucKR = "euc-kr", cp949
+}
+struct DocumentOptions: Codable {
+    let format: DocumentFormat
+    let encoding: DocumentEncoding?
+    let firstPage: Int?
+    let pageLimit: Int?
+    let lineLimit: Int?
+    let cursor: DocumentTextCursor?
+    init(format: DocumentFormat, encoding: DocumentEncoding?, firstPage: Int?, pageLimit: Int?,
+         lineLimit: Int?, cursor: DocumentTextCursor? = nil) {
+        self.format = format; self.encoding = encoding; self.firstPage = firstPage
+        self.pageLimit = pageLimit; self.lineLimit = lineLimit; self.cursor = cursor
+    }
+}
+// Internal scalar position only. The gateway owns external opaque cursor authorization.
+struct DocumentTextCursor: Codable, Equatable {
+    let originalSha256: String
+    let representationSha256: String
+    let offset: Int
+    func validate() throws {
+        guard HelperCodec.matches(originalSha256, "^[0-9a-f]{64}$"),
+              HelperCodec.matches(representationSha256, "^[0-9a-f]{64}$"),
+              (1..<HelperLimits.preparedTextBytes).contains(offset) else { throw HelperProtocolError.invalidCursor }
+    }
+}
+struct DocumentTextRange: Codable {
+    let start: Int
+    let end: Int
+    let totalScalars: Int
+    let totalBytes: Int
+}
+struct DocumentRequest: Codable {
+    let version: Int
+    let requestId: String
+    let operation: DocumentOperation
+    let originalBase64: String
+    let options: DocumentOptions
+    func originalBytes() throws -> Data {
+        try HelperCodec.base64(originalBase64, maximum: HelperLimits.originalBytes)
+    }
+}
+
+private enum Discriminator: String, CodingKey { case operation, type }
+enum HelperRequest: Codable {
+    case selector(SelectorRequest), document(DocumentRequest)
+    var requestId: String {
+        switch self { case .selector(let value): return value.requestId; case .document(let value): return value.requestId }
+    }
+    init(from decoder: Decoder) throws {
+        let operation = try decoder.container(keyedBy: Discriminator.self).decode(String.self, forKey: .operation)
+        switch operation {
+        case "selector.list", "selector.snapshot": self = .selector(try SelectorRequest(from: decoder))
+        case "document.inspect", "document.text", "document.pages", "document.ocr": self = .document(try DocumentRequest(from: decoder))
+        default: throw HelperProtocolError.invalidOperation
+        }
+    }
+    func encode(to encoder: Encoder) throws {
+        switch self { case .selector(let value): try value.encode(to: encoder); case .document(let value): try value.encode(to: encoder) }
+    }
+}
+
+enum NativeEntryKind: String, Codable { case directory, file, disabled }
+struct NativeEntry: Codable {
+    let name: String
+    let kind: NativeEntryKind
+    let identity: NativeIdentity?
+    let selectable: Bool
+    let reason: String?
+}
+struct SelectorListed: Codable {
+    let requestId: String
+    let entries: [NativeEntry]
+    let nextName: String?
+}
+struct SnapshotChunk: Codable {
+    let requestId: String
+    let index: Int
+    let base64: String
+}
+struct SnapshotComplete: Codable {
+    let requestId: String
+    let before: NativeIdentity
+    let after: NativeIdentity
+    let bytes: Int
+    let sha256: String
+}
+enum PageRepresentation: String, Codable {
+    case nativeText = "native-text", renderedImage = "rendered-image", ocrText = "ocr-text", verifiedBlank = "verified-blank"
+}
+struct PageCoverage: Codable {
+    let page: Int
+    let representation: PageRepresentation
+}
+struct DocumentCoverage: Codable {
+    let totalPages: Int
+    let pages: [PageCoverage]
+}
+enum ImageMIME: String, Codable { case jpeg = "image/jpeg", png = "image/png" }
+struct HelperImage: Codable {
+    let data: String
+    let mimeType: ImageMIME
+}
+enum HelperContent: Codable {
+    case text(String), image(HelperImage)
+    private enum Keys: String, CodingKey { case type, text }
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: Keys.self)
+        switch try container.decode(String.self, forKey: .type) {
+        case "text": self = .text(try container.decode(String.self, forKey: .text))
+        case "image": self = .image(try HelperImage(from: decoder))
+        default: throw HelperProtocolError.invalidShape
+        }
+    }
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: Keys.self)
+        switch self {
+        case .text(let text):
+            try container.encode("text", forKey: .type)
+            try container.encode(text, forKey: .text)
+        case .image(let image):
+            try container.encode("image", forKey: .type)
+            try image.encode(to: encoder)
+        }
+    }
+}
+struct DocumentComplete: Codable {
+    let requestId: String
+    let originalSha256: String
+    let representationSha256: String
+    let coverage: DocumentCoverage
+    let content: [HelperContent]
+    let textRange: DocumentTextRange?
+    let nextCursor: DocumentTextCursor?
+    init(requestId: String, originalSha256: String, representationSha256: String,
+         coverage: DocumentCoverage, content: [HelperContent],
+         textRange: DocumentTextRange? = nil, nextCursor: DocumentTextCursor? = nil) {
+        self.requestId = requestId; self.originalSha256 = originalSha256
+        self.representationSha256 = representationSha256; self.coverage = coverage
+        self.content = content; self.textRange = textRange; self.nextCursor = nextCursor
+    }
+}
+
+struct PreparedTextPage: Codable {
+    let page: Int
+    let representation: PageRepresentation
+    let text: String
+}
+
+// Exact canonical per-page text, already produced by T4. This type does not parse or authorize.
+struct PreparedDocumentText {
+    private let pages: [PreparedTextPage]
+    let bytes: Int
+    let scalars: Int
+    let sha256: String
+    let totalPages: Int
+
+    init(pages: [PreparedTextPage], totalPages: Int? = nil) throws {
+        let total = totalPages ?? pages.count
+        guard (1...300).contains(pages.count), (pages.count...300).contains(total) else { throw HelperProtocolError.invalidBounds }
+        var bytes = 0, scalars = 0, previous = 0
+        var digest = SHA256()
+        for page in pages {
+            guard page.page > previous, page.page <= total, !page.text.contains("\0"),
+                  page.representation != .renderedImage,
+                  page.representation != .verifiedBlank || page.text.isEmpty else { throw HelperProtocolError.invalidShape }
+            bytes += page.text.utf8.count
+            guard bytes <= HelperLimits.preparedTextBytes else { throw HelperProtocolError.invalidBounds }
+            scalars += page.text.unicodeScalars.count
+            digest.update(data: Data(page.text.utf8))
+            previous = page.page
+        }
+        self.pages = pages; self.bytes = bytes; self.scalars = scalars; self.totalPages = total
+        self.sha256 = digest.finalize().map({ String(format: "%02x", $0) }).joined()
+    }
+
+    func frame(for request: DocumentRequest) throws -> HelperFrame {
+        try HelperCodec.validate(.document(request))
+        guard request.operation == .text || request.operation == .ocr else { throw HelperProtocolError.invalidOperation }
+        let original = SHA256.hash(data: try request.originalBytes()).map({ String(format: "%02x", $0) }).joined()
+        let start = request.options.cursor?.offset ?? 0
+        if let cursor = request.options.cursor {
+            guard cursor.originalSha256 == original, cursor.representationSha256 == sha256,
+                  start < scalars else { throw HelperProtocolError.invalidCursor }
+        }
+        var text = "", position = 0, end = start, written = 0, lines = 0
+        read: for page in pages {
+            for scalar in page.text.unicodeScalars {
+                defer { position += 1 }
+                if position < start { continue }
+                let part = String(scalar)
+                guard written + part.utf8.count <= HelperLimits.textBytes,
+                      lines < (request.options.lineLimit ?? 2000) else { break read }
+                text.unicodeScalars.append(scalar)
+                written += part.utf8.count
+                end += 1
+                if scalar.value == 10 { lines += 1 }
+            }
+        }
+        var pageStart = 0
+        var coverage: [PageCoverage] = []
+        for page in pages {
+            let pageEnd = pageStart + page.text.unicodeScalars.count
+            let intersects = pageStart < end && pageEnd > start
+            let emptyAtBoundary = pageStart == pageEnd && pageStart >= start &&
+                (pageStart < end || (pageStart == scalars && end == scalars))
+            if intersects || emptyAtBoundary {
+                coverage.append(PageCoverage(page: page.page, representation: page.representation))
+            }
+            pageStart = pageEnd
+        }
+        let next = end < scalars ? DocumentTextCursor(originalSha256: original, representationSha256: sha256, offset: end) : nil
+        let result = HelperFrame.documentComplete(DocumentComplete(requestId: request.requestId, originalSha256: original,
+            representationSha256: sha256, coverage: DocumentCoverage(totalPages: totalPages, pages: coverage),
+            content: [.text(text)], textRange: DocumentTextRange(start: start, end: end, totalScalars: scalars, totalBytes: bytes),
+            nextCursor: next))
+        var state = try HelperFrameState(request: .document(request))
+        try state.accept(result)
+        try state.finish()
+        return result
+    }
+}
+enum HelperFailureCode: String, Codable {
+    case hostAccessDenied = "host_access_denied", fileChanged = "file_changed", invalidPDF = "invalid_pdf"
+    case passwordRequired = "password_required", encodingRequired = "encoding_required"
+    case unsupportedEncoding = "unsupported_encoding", ocrFailed = "ocr_failed", processingLimit = "processing_limit"
+}
+struct HelperFailure: Codable {
+    let requestId: String
+    let code: HelperFailureCode
+}
+enum HelperFrame: Codable {
+    case listed(SelectorListed), chunk(SnapshotChunk), snapshotComplete(SnapshotComplete)
+    case documentComplete(DocumentComplete), error(HelperFailure)
+    var requestId: String {
+        switch self {
+        case .listed(let value): return value.requestId
+        case .chunk(let value): return value.requestId
+        case .snapshotComplete(let value): return value.requestId
+        case .documentComplete(let value): return value.requestId
+        case .error(let value): return value.requestId
+        }
+    }
+    init(from decoder: Decoder) throws {
+        let type = try decoder.container(keyedBy: Discriminator.self).decode(String.self, forKey: .type)
+        switch type {
+        case "selector.listed": self = .listed(try SelectorListed(from: decoder))
+        case "chunk": self = .chunk(try SnapshotChunk(from: decoder))
+        case "snapshot.complete": self = .snapshotComplete(try SnapshotComplete(from: decoder))
+        case "document.complete": self = .documentComplete(try DocumentComplete(from: decoder))
+        case "error": self = .error(try HelperFailure(from: decoder))
+        default: throw HelperProtocolError.invalidOperation
+        }
+    }
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: Discriminator.self)
+        switch self {
+        case .listed(let value):
+            try container.encode("selector.listed", forKey: .type); try value.encode(to: encoder)
+        case .chunk(let value):
+            try container.encode("chunk", forKey: .type); try value.encode(to: encoder)
+        case .snapshotComplete(let value):
+            try container.encode("snapshot.complete", forKey: .type); try value.encode(to: encoder)
+        case .documentComplete(let value):
+            try container.encode("document.complete", forKey: .type); try value.encode(to: encoder)
+        case .error(let value):
+            try container.encode("error", forKey: .type); try value.encode(to: encoder)
+        }
+    }
+}
+
+enum HelperCodec {
+    static func matches(_ value: String, _ pattern: String) -> Bool {
+        value.range(of: pattern, options: .regularExpression) == value.startIndex..<value.endIndex
+    }
+    static func base64(_ value: String, maximum: Int) throws -> Data {
+        guard value.utf8.count <= ((maximum + 2) / 3) * 4,
+              let decoded = Data(base64Encoded: value), !decoded.isEmpty, decoded.count <= maximum,
+              decoded.base64EncodedString() == value else { throw HelperProtocolError.invalidBase64 }
+        return decoded
+    }
+    private static func strict<T: Codable>(_ type: T.Type, data: Data) throws -> T {
+        guard String(data: data, encoding: .utf8) != nil else { throw HelperProtocolError.invalidJSON }
+        let decoded = try JSONDecoder().decode(type, from: data)
+        // Foundation Codable ignores unknown keys. Compare JSON values (not spelling)
+        // against its exact encoded shape, recursively, to reject extras and null optionals.
+        guard let original = try JSONSerialization.jsonObject(with: data) as? NSDictionary,
+              let normalized = try JSONSerialization.jsonObject(with: JSONEncoder().encode(decoded)) as? NSDictionary,
+              original.isEqual(normalized) else { throw HelperProtocolError.invalidShape }
+        return decoded
+    }
+    static func validate(_ request: HelperRequest) throws {
+        guard matches(request.requestId, #"^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$"#) else {
+            throw HelperProtocolError.invalidShape
+        }
+        switch request {
+        case .selector(let value):
+            guard value.version == 1, value.segments.count <= 256,
+                  value.segments.allSatisfy({ !$0.isEmpty && $0 != "." && $0 != ".." && !$0.contains("/") && !$0.contains("\0") }),
+                  value.query.map({ $0.unicodeScalars.count <= 200 }) ?? true,
+                  value.afterName.map({ !$0.isEmpty }) ?? true else { throw HelperProtocolError.invalidBounds }
+            switch value.operation {
+            case .list:
+                guard value.showHidden != nil, value.expectedIdentity == nil else { throw HelperProtocolError.invalidShape }
+            case .snapshot:
+                guard let identity = value.expectedIdentity, value.showHidden == nil,
+                      value.query == nil, value.afterName == nil else { throw HelperProtocolError.invalidShape }
+                try identity.validate()
+            }
+        case .document(let value):
+            guard value.version == 1,
+                  value.options.firstPage.map({ (1...300).contains($0) }) ?? true,
+                  value.options.pageLimit.map({ (1...2).contains($0) }) ?? true,
+                  value.options.lineLimit.map({ (1...2000).contains($0) }) ?? true else { throw HelperProtocolError.invalidBounds }
+            _ = try value.originalBytes()
+            if let cursor = value.options.cursor {
+                guard value.operation == .text || value.operation == .ocr else { throw HelperProtocolError.invalidCursor }
+                try cursor.validate()
+                let original = SHA256.hash(data: try value.originalBytes()).map({ String(format: "%02x", $0) }).joined()
+                guard cursor.originalSha256 == original else { throw HelperProtocolError.invalidCursor }
+            }
+        }
+    }
+    static func decodeRequest(_ data: Data, privilege: HelperPrivilege) throws -> HelperRequest {
+        guard data.count <= HelperLimits.requestBytes else { throw HelperProtocolError.invalidBounds }
+        let request = try strict(HelperRequest.self, data: data)
+        switch (request, privilege) {
+        case (.selector, .selector), (.document, .document): break
+        default: throw HelperProtocolError.wrongPrivilege
+        }
+        try validate(request)
+        return request
+    }
+    static func encodeRequest(_ request: HelperRequest) throws -> Data {
+        try validate(request)
+        let data = try JSONEncoder().encode(request)
+        guard data.count <= HelperLimits.requestBytes else { throw HelperProtocolError.invalidBounds }
+        return data
+    }
+    static func readRequest(from input: FileHandle, privilege: HelperPrivilege) throws -> HelperRequest {
+        var data = Data()
+        while let part = try input.read(upToCount: min(65_536, HelperLimits.requestBytes + 1 - data.count)), !part.isEmpty {
+            data.append(part)
+            guard data.count <= HelperLimits.requestBytes else { throw HelperProtocolError.invalidBounds }
+        }
+        return try decodeRequest(data, privilege: privilege)
+    }
+    static func decodeFrame(_ data: Data) throws -> HelperFrame {
+        guard data.count <= HelperLimits.frameBytes else { throw HelperProtocolError.invalidBounds }
+        let frame = try strict(HelperFrame.self, data: data)
+        try validate(frame)
+        return frame
+    }
+    static func encodeFrame(_ frame: HelperFrame) throws -> Data {
+        try validate(frame)
+        var data = try JSONEncoder().encode(frame)
+        guard data.count <= HelperLimits.frameBytes else { throw HelperProtocolError.invalidBounds }
+        data.append(10)
+        return data
+    }
+    static func validate(_ frame: HelperFrame) throws {
+        guard matches(frame.requestId, #"^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$"#) else {
+            throw HelperProtocolError.invalidShape
+        }
+        switch frame {
+        case .listed(let value):
+            guard value.entries.count <= 50, value.nextName.map({ !$0.isEmpty }) ?? true else { throw HelperProtocolError.invalidBounds }
+            for entry in value.entries {
+                guard !entry.name.isEmpty, entry.reason.map({ !$0.isEmpty }) ?? true else { throw HelperProtocolError.invalidShape }
+                try entry.identity?.validate()
+            }
+        case .chunk(let value):
+            guard (0...HelperLimits.originalBytes).contains(value.index) else { throw HelperProtocolError.invalidBounds }
+            _ = try base64(value.base64, maximum: HelperLimits.originalBytes)
+        case .snapshotComplete(let value):
+            try value.before.validate(); try value.after.validate()
+            guard (1...HelperLimits.originalBytes).contains(value.bytes), matches(value.sha256, "^[0-9a-f]{64}$") else {
+                throw HelperProtocolError.invalidBounds
+            }
+        case .documentComplete(let value):
+            guard matches(value.originalSha256, "^[0-9a-f]{64}$"), matches(value.representationSha256, "^[0-9a-f]{64}$"),
+                  (1...300).contains(value.coverage.totalPages), value.coverage.pages.count <= 300,
+                  value.coverage.pages.allSatisfy({ (1...value.coverage.totalPages).contains($0.page) }),
+                  value.content.count <= 2000 else { throw HelperProtocolError.invalidBounds }
+            var textBytes = 0
+            var images = 0
+            for content in value.content {
+                switch content {
+                case .text(let text): textBytes += text.utf8.count
+                case .image(let image):
+                    images += 1
+                    _ = try base64(image.data, maximum: HelperLimits.imageBytes)
+                }
+            }
+            guard textBytes <= HelperLimits.textBytes, images <= 2 else { throw HelperProtocolError.invalidBounds }
+            if let range = value.textRange {
+                guard range.start >= 0, range.end >= range.start, range.end <= range.totalScalars,
+                      range.totalScalars <= range.totalBytes, range.totalBytes <= HelperLimits.preparedTextBytes,
+                      range.totalBytes <= range.totalScalars * 4,
+                      range.end > range.start || range.totalScalars == 0,
+                      value.content.count == 1, case .text(let text) = value.content[0],
+                      text.unicodeScalars.count == range.end - range.start,
+                      text.utf8.count <= range.totalBytes else { throw HelperProtocolError.invalidBounds }
+                let remainingScalars = range.totalScalars - (range.end - range.start)
+                let remainingBytes = range.totalBytes - textBytes
+                guard remainingBytes >= remainingScalars,
+                      remainingBytes <= remainingScalars * 4 else { throw HelperProtocolError.invalidBounds }
+                if range.end < range.totalScalars {
+                    guard let cursor = value.nextCursor, cursor.offset == range.end,
+                          cursor.originalSha256 == value.originalSha256,
+                          cursor.representationSha256 == value.representationSha256 else { throw HelperProtocolError.invalidCursor }
+                    try cursor.validate()
+                } else {
+                    guard value.nextCursor == nil else { throw HelperProtocolError.invalidCursor }
+                }
+                if range.start == 0 && range.end == range.totalScalars {
+                    let digest = SHA256.hash(data: Data(text.utf8)).map({ String(format: "%02x", $0) }).joined()
+                    guard value.representationSha256 == digest, text.utf8.count == range.totalBytes else {
+                        throw HelperProtocolError.invalidSnapshot
+                    }
+                }
+            } else if value.nextCursor != nil { throw HelperProtocolError.invalidCursor }
+        case .error: break
+        }
+    }
+    static func readFrames(from input: FileHandle, request: HelperRequest, emit: (HelperFrame) throws -> Void) throws {
+        var state = try HelperFrameState(request: request)
+        var line = Data()
+        var total = 0
+        while let part = try input.read(upToCount: 65_536), !part.isEmpty {
+            total += part.count
+            guard total <= HelperLimits.streamBytes else { throw HelperProtocolError.invalidBounds }
+            for byte in part {
+                if byte == 10 {
+                    let frame = try decodeFrame(line)
+                    try state.accept(frame)
+                    try emit(frame)
+                    line.removeAll(keepingCapacity: true)
+                } else {
+                    guard line.count < HelperLimits.frameBytes else { throw HelperProtocolError.invalidBounds }
+                    line.append(byte)
+                }
+            }
+        }
+        guard line.isEmpty else { throw HelperProtocolError.invalidJSON }
+        try state.finish()
+    }
+}
+
+struct HelperFrameState {
+    private let request: HelperRequest
+    private var terminal = false
+    private var nextIndex = 0
+    private var bytes = 0
+    private var digest = SHA256()
+
+    init(request: HelperRequest) throws {
+        try HelperCodec.validate(request)
+        self.request = request
+    }
+    mutating func accept(_ frame: HelperFrame) throws {
+        guard !terminal else { throw HelperProtocolError.terminalState }
+        guard frame.requestId == request.requestId else { throw HelperProtocolError.requestMismatch }
+        try HelperCodec.validate(frame)
+        switch (request, frame) {
+        case (_, .error): terminal = true
+        case (.selector(let selection), .listed):
+            guard selection.operation == .list else { throw HelperProtocolError.invalidSequence }
+            terminal = true
+        case (.selector(let selection), .chunk(let chunk)):
+            guard selection.operation == .snapshot, chunk.index == nextIndex else { throw HelperProtocolError.invalidSequence }
+            let data = try HelperCodec.base64(chunk.base64, maximum: HelperLimits.originalBytes)
+            guard bytes + data.count <= HelperLimits.originalBytes else { throw HelperProtocolError.invalidBounds }
+            bytes += data.count
+            nextIndex += 1
+            digest.update(data: data)
+        case (.selector(let selection), .snapshotComplete(let value)):
+            guard selection.operation == .snapshot, nextIndex > 0, bytes == value.bytes,
+                  value.before == selection.expectedIdentity, value.after == value.before,
+                  value.bytes == value.before.size,
+                  value.sha256 == digest.finalize().map({ String(format: "%02x", $0) }).joined() else {
+                throw HelperProtocolError.invalidSnapshot
+            }
+            terminal = true
+        case (.document(let document), .documentComplete(let value)):
+            let originalDigest = SHA256.hash(data: try document.originalBytes()).map({ String(format: "%02x", $0) }).joined()
+            guard value.originalSha256 == originalDigest else { throw HelperProtocolError.invalidSnapshot }
+            var lines = 0
+            for content in value.content {
+                if case .text(let text) = content, !text.isEmpty {
+                    lines += text.utf8.filter({ $0 == 10 }).count + (text.hasSuffix("\n") ? 0 : 1)
+                }
+            }
+            guard lines <= (document.options.lineLimit ?? 2000) else { throw HelperProtocolError.invalidBounds }
+            if document.operation == .text || document.operation == .ocr {
+                guard let range = value.textRange, range.start == (document.options.cursor?.offset ?? 0) else {
+                    throw HelperProtocolError.invalidCursor
+                }
+                if let cursor = document.options.cursor {
+                    guard value.representationSha256 == cursor.representationSha256 else { throw HelperProtocolError.invalidCursor }
+                }
+            } else {
+                guard value.textRange == nil, value.nextCursor == nil else { throw HelperProtocolError.invalidCursor }
+            }
+            if document.operation == .pages {
+                let first = document.options.firstPage ?? 1
+                let end = min(first + (document.options.pageLimit ?? 2), value.coverage.totalPages + 1)
+                guard first < end, Set(value.coverage.pages.map(\.page)) == Set(first..<end) else {
+                    throw HelperProtocolError.invalidBounds
+                }
+            }
+            terminal = true
+        default: throw HelperProtocolError.invalidSequence
+        }
+    }
+    func finish() throws {
+        guard terminal else { throw HelperProtocolError.missingTerminal }
+    }
+}
+
+// Entrypoints select their privilege before reading stdin and pass writer.emit to
+// HostSelector.handle(_:emit:) OR DocumentRead.handle(_:emit:), never a fallback.
+// They must call finish() and require normal child exit before publishing success.
+final class HelperFrameWriter {
+    private var state: HelperFrameState
+    private let output: FileHandle
+    private var written = 0
+    private var failed = false
+    init(request: HelperRequest, output: FileHandle) throws {
+        state = try HelperFrameState(request: request)
+        self.output = output
+    }
+    func emit(_ frame: HelperFrame) throws {
+        guard !failed else { throw HelperProtocolError.terminalState }
+        do {
+            var next = state
+            try next.accept(frame)
+            let data = try HelperCodec.encodeFrame(frame)
+            guard written + data.count <= HelperLimits.streamBytes else { throw HelperProtocolError.invalidBounds }
+            try output.write(contentsOf: data)
+            state = next
+            written += data.count
+        } catch {
+            failed = true
+            throw error
+        }
+    }
+    func finish() throws {
+        guard !failed else { throw HelperProtocolError.terminalState }
+        try state.finish()
+    }
+}

package/host/document-reader/main.swift

@@ -0,0 +1,22 @@
+import Foundation
+import Darwin
+
+// Selector-only executable. DocumentRead and PDFKit/Vision are not linked here.
+signal(SIGPIPE, SIG_IGN)
+do {
+    let request = try HelperCodec.readRequest(from: .standardInput, privilege: .selector)
+    guard case .selector(let selector) = request else { throw HelperProtocolError.wrongPrivilege }
+    let writer = try HelperFrameWriter(request: request, output: .standardOutput)
+    do {
+        try HostSelector.handle(selector, emit: writer.emit)
+        try writer.finish()
+    } catch let failure as SelectorFailure {
+        try writer.emit(.error(HelperFailure(requestId: selector.requestId, code: failure.code)))
+        try writer.finish()
+        exit(1)
+    }
+} catch {
+    // Never print private paths, OS error text, or input on protocol failure.
+    try? FileHandle.standardError.write(contentsOf: Data("selector_failed\n".utf8))
+    exit(1)
+}