@hasna/recordings 0.2.11 → 0.2.13

package/src/native/Recordings/Updater/Client/ClientMain.swift

@@ -0,0 +1,119 @@
+import Darwin
+import Foundation
+import RecordingsUpdateProtocol
+
+@main
+enum RecordingsUpdateClientMain {
+    static func main() {
+        do {
+            let command = try ClientCommand.parse(CommandLine.arguments)
+            let connection = NSXPCConnection(
+                machServiceName: RecordingsUpdateConstants.machServiceName,
+                options: .privileged
+            )
+            connection.remoteObjectInterface = makeRecordingsUpdateXPCInterface()
+            connection.resume()
+            defer { connection.invalidate() }
+            let reply: NSDictionary
+            switch command {
+            case .status:
+                reply = try invoke(connection: connection) { service, callback in
+                    service.queryStatus(withReply: callback)
+                }
+            case let .install(artifactPath, manifestPath, envelopePath):
+                let artifact = try retainedRegularFile(path: artifactPath)
+                let manifest = try retainedRegularFile(path: manifestPath)
+                let envelope = try retainedRegularFile(path: envelopePath)
+                defer {
+                    try? artifact.close()
+                    try? manifest.close()
+                    try? envelope.close()
+                }
+                reply = try invoke(connection: connection) { service, callback in
+                    service.install(
+                        archive: artifact,
+                        manifest: manifest,
+                        envelope: envelope,
+                        withReply: callback
+                    )
+                }
+            }
+            let data = try JSONSerialization.data(withJSONObject: reply, options: [.sortedKeys])
+            FileHandle.standardOutput.write(data + Data([0x0a]))
+            guard reply[RecordingsUpdateReplyKey.success] as? Bool == true else { Darwin.exit(1) }
+        } catch {
+            FileHandle.standardError.write(Data("recordings-update-client: request failed\n".utf8))
+            Darwin.exit(1)
+        }
+    }
+
+    private static func invoke(
+        connection: NSXPCConnection,
+        operation: (RecordingsUpdateXPCProtocol, @escaping (NSDictionary) -> Void) -> Void
+    ) throws -> NSDictionary {
+        let semaphore = DispatchSemaphore(value: 0)
+        let lock = NSLock()
+        var result: NSDictionary?
+        var failed = false
+        let proxy = connection.remoteObjectProxyWithErrorHandler { _ in
+            lock.lock(); failed = true; lock.unlock()
+            semaphore.signal()
+        }
+        guard let service = proxy as? RecordingsUpdateXPCProtocol else {
+            throw ClientError.brokerUnavailable
+        }
+        operation(service) { reply in
+            lock.lock(); result = reply; lock.unlock()
+            semaphore.signal()
+        }
+        guard semaphore.wait(timeout: .now() + 300) == .success else {
+            throw ClientError.timeout
+        }
+        lock.lock(); defer { lock.unlock() }
+        guard !failed, let result else { throw ClientError.brokerUnavailable }
+        return result
+    }
+
+    private static func retainedRegularFile(path: String) throws -> FileHandle {
+        guard path.hasPrefix("/") else { throw ClientError.invalidArguments }
+        let descriptor = Darwin.open(path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW)
+        guard descriptor >= 0 else { throw ClientError.invalidInput }
+        var metadata = stat()
+        guard fstat(descriptor, &metadata) == 0,
+              (metadata.st_mode & S_IFMT) == S_IFREG,
+              metadata.st_size > 0
+        else {
+            Darwin.close(descriptor)
+            throw ClientError.invalidInput
+        }
+        return FileHandle(fileDescriptor: descriptor, closeOnDealloc: true)
+    }
+}
+
+private enum ClientCommand {
+    case status
+    case install(artifact: String, manifest: String, envelope: String)
+
+    static func parse(_ arguments: [String]) throws -> ClientCommand {
+        if arguments.count == 2, arguments[1] == "status" { return .status }
+        guard arguments.count == 8,
+              arguments[1] == "install" || arguments[1] == "bootstrap",
+              arguments[2] == "--artifact",
+              arguments[4] == "--manifest",
+              arguments[6] == "--envelope",
+              arguments[3].hasPrefix("/"),
+              arguments[5].hasPrefix("/"),
+              arguments[7].hasPrefix("/")
+        else {
+            throw ClientError.invalidArguments
+        }
+        return .install(artifact: arguments[3], manifest: arguments[5], envelope: arguments[7])
+    }
+}
+
+private enum ClientError: Error {
+    case invalidArguments
+    case invalidInput
+    case brokerUnavailable
+    case timeout
+}

package/src/native/Recordings/Updater/Protocol/BoundedProcess.swift

@@ -0,0 +1,159 @@
+import Darwin
+import Foundation
+
+public struct BoundedProcessResult: Sendable {
+    public let standardOutput: Data
+    public let exitedNormally: Bool
+    public let terminationStatus: Int32
+}
+
+public enum BoundedProcessError: Error, Equatable, Sendable {
+    case invalidConfiguration
+    case launchFailed
+    case timedOut
+    case outputTooLarge
+    case outputReadFailed
+}
+
+/// Runs a fixed executable with bounded stdout and a hard wall-clock deadline.
+///
+/// Stdout is drained with nonblocking `poll(2)`, preventing either the child or an
+/// inherited-pipe descendant from extending the wall-clock bound. The reader
+/// retains at most `maximumOutputBytes`; the first byte beyond that limit kills the
+/// direct child, closes the pipe, and fails closed.
+public enum BoundedProcessRunner {
+    public static func run(
+        executablePath: String,
+        arguments: [String],
+        environment: [String: String],
+        maximumOutputBytes: Int,
+        timeout: TimeInterval
+    ) throws -> BoundedProcessResult {
+        guard executablePath.hasPrefix("/"),
+              maximumOutputBytes >= 0,
+              timeout > 0,
+              timeout <= 3_600,
+              timeout.isFinite
+        else {
+            throw BoundedProcessError.invalidConfiguration
+        }
+
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: executablePath)
+        process.arguments = arguments
+        process.environment = environment
+        process.standardInput = FileHandle.nullDevice
+        let output = Pipe()
+        process.standardOutput = output
+        process.standardError = FileHandle.nullDevice
+        do {
+            try process.run()
+        } catch {
+            throw BoundedProcessError.launchFailed
+        }
+
+        let processIdentifier = process.processIdentifier
+        let outputHandle = output.fileHandleForReading
+        let outputDescriptor = outputHandle.fileDescriptor
+        let existingFlags = Darwin.fcntl(outputDescriptor, F_GETFL)
+        guard existingFlags >= 0,
+              Darwin.fcntl(outputDescriptor, F_SETFL, existingFlags | O_NONBLOCK) >= 0
+        else {
+            if process.isRunning { _ = Darwin.kill(processIdentifier, SIGKILL) }
+            process.waitUntilExit()
+            throw BoundedProcessError.outputReadFailed
+        }
+        let startedAt = DispatchTime.now().uptimeNanoseconds
+        let timeoutNanoseconds = UInt64(timeout * 1_000_000_000)
+        let deadline = startedAt + timeoutNanoseconds
+
+        var standardOutput = Data()
+        var outputTooLarge = false
+        var outputReadFailed = false
+        var timedOut = false
+        var reachedEOF = false
+        var buffer = [UInt8](repeating: 0, count: 4_096)
+        while !reachedEOF && !outputTooLarge && !outputReadFailed {
+            let now = DispatchTime.now().uptimeNanoseconds
+            if now >= deadline {
+                timedOut = true
+                break
+            }
+            let remainingNanoseconds = deadline - now
+            let remainingMilliseconds = max(
+                1,
+                min(
+                    Int(Int32.max),
+                    Int((remainingNanoseconds + 999_999) / 1_000_000)
+                )
+            )
+            var descriptor = pollfd(
+                fd: outputDescriptor,
+                events: Int16(POLLIN | POLLHUP | POLLERR),
+                revents: 0
+            )
+            let pollResult = Darwin.poll(&descriptor, 1, Int32(remainingMilliseconds))
+            if pollResult == 0 {
+                timedOut = true
+                break
+            }
+            if pollResult < 0 {
+                if errno == EINTR { continue }
+                outputReadFailed = true
+                break
+            }
+            while true {
+                let count = buffer.withUnsafeMutableBytes { bytes in
+                    Darwin.read(outputDescriptor, bytes.baseAddress, bytes.count)
+                }
+                if count > 0 {
+                    if count > maximumOutputBytes - standardOutput.count {
+                        outputTooLarge = true
+                        break
+                    }
+                    standardOutput.append(contentsOf: buffer.prefix(count))
+                    continue
+                }
+                if count == 0 {
+                    reachedEOF = true
+                    break
+                }
+                if errno == EINTR { continue }
+                if errno == EAGAIN || errno == EWOULDBLOCK { break }
+                outputReadFailed = true
+                break
+            }
+        }
+
+        while !timedOut && !outputTooLarge && !outputReadFailed && process.isRunning {
+            let now = DispatchTime.now().uptimeNanoseconds
+            if now >= deadline {
+                timedOut = true
+                break
+            }
+            let remaining = Double(deadline - now) / 1_000_000_000
+            Thread.sleep(forTimeInterval: min(0.005, remaining))
+        }
+
+        if timedOut || outputTooLarge || outputReadFailed {
+            if process.isRunning {
+                _ = Darwin.kill(processIdentifier, SIGKILL)
+            }
+            do {
+                try outputHandle.close()
+            } catch {
+                outputReadFailed = true
+            }
+        }
+        process.waitUntilExit()
+
+        if timedOut { throw BoundedProcessError.timedOut }
+        if outputTooLarge { throw BoundedProcessError.outputTooLarge }
+        if outputReadFailed { throw BoundedProcessError.outputReadFailed }
+        return BoundedProcessResult(
+            standardOutput: standardOutput,
+            exitedNormally: process.terminationReason == .exit,
+            terminationStatus: process.terminationStatus
+        )
+    }
+}

package/src/native/Recordings/Updater/Protocol/CandidateMetadataPolicy.swift

@@ -0,0 +1,214 @@
+import Foundation
+
+public struct CandidateReleaseMetadataExpectation: Equatable, Sendable {
+    public let applicationIdentifier: String
+    public let applicationExecutable: String
+    public let version: String
+    public let build: String
+    public let sourceCommit: String
+    public let signingTeamIdentifier: String
+    public let minimumOSVersion: String
+    public let architectures: [String]
+
+    public init(
+        applicationIdentifier: String,
+        applicationExecutable: String,
+        version: String,
+        build: String,
+        sourceCommit: String,
+        signingTeamIdentifier: String,
+        minimumOSVersion: String,
+        architectures: [String]
+    ) {
+        self.applicationIdentifier = applicationIdentifier
+        self.applicationExecutable = applicationExecutable
+        self.version = version
+        self.build = build
+        self.sourceCommit = sourceCommit
+        self.signingTeamIdentifier = signingTeamIdentifier
+        self.minimumOSVersion = minimumOSVersion
+        self.architectures = architectures
+    }
+}
+
+public struct CandidateApplicationMetadata: Equatable, Sendable {
+    public let bundleIdentifier: String
+    public let shortVersion: String
+    public let buildVersion: String
+    public let executable: String
+    public let minimumOSVersion: String
+    public let architectures: [String]
+
+    public init(
+        bundleIdentifier: String,
+        shortVersion: String,
+        buildVersion: String,
+        executable: String,
+        minimumOSVersion: String,
+        architectures: [String]
+    ) {
+        self.bundleIdentifier = bundleIdentifier
+        self.shortVersion = shortVersion
+        self.buildVersion = buildVersion
+        self.executable = executable
+        self.minimumOSVersion = minimumOSVersion
+        self.architectures = architectures
+    }
+}
+
+public struct CandidateCompanionMetadata: Equatable, Sendable {
+    public let sha256: String
+    public let architectures: [String]
+
+    public init(sha256: String, architectures: [String]) {
+        self.sha256 = sha256
+        self.architectures = architectures
+    }
+}
+
+public struct CandidateBuildProvenanceMetadata: Equatable, Sendable {
+    public let schemaVersion: Int
+    public let containsLocalOnlyFields: Bool
+    public let bundleIdentifier: String
+    public let bundleVersion: String
+    public let bundleBuildVersion: String
+    public let sourceCommit: String
+    public let teamIdentifier: String
+    public let minimumMacOS: String
+    public let architectures: [String]
+    public let companionVersion: String
+    public let companionSHA256: String
+    public let companionArchitectures: [String]
+
+    public init(
+        schemaVersion: Int,
+        containsLocalOnlyFields: Bool,
+        bundleIdentifier: String,
+        bundleVersion: String,
+        bundleBuildVersion: String,
+        sourceCommit: String,
+        teamIdentifier: String,
+        minimumMacOS: String,
+        architectures: [String],
+        companionVersion: String,
+        companionSHA256: String,
+        companionArchitectures: [String]
+    ) {
+        self.schemaVersion = schemaVersion
+        self.containsLocalOnlyFields = containsLocalOnlyFields
+        self.bundleIdentifier = bundleIdentifier
+        self.bundleVersion = bundleVersion
+        self.bundleBuildVersion = bundleBuildVersion
+        self.sourceCommit = sourceCommit
+        self.teamIdentifier = teamIdentifier
+        self.minimumMacOS = minimumMacOS
+        self.architectures = architectures
+        self.companionVersion = companionVersion
+        self.companionSHA256 = companionSHA256
+        self.companionArchitectures = companionArchitectures
+    }
+}
+
+public enum CandidateMetadataPolicyError: Error, Equatable, Sendable {
+    case applicationIdentifierMismatch
+    case applicationVersionMismatch
+    case applicationBuildMismatch
+    case applicationExecutableMismatch
+    case applicationMinimumOSMismatch
+    case applicationArchitectureMismatch
+    case updateClientArchitectureMismatch
+    case companionDigestMismatch
+    case companionArchitectureMismatch
+    case provenanceSchemaMismatch
+    case localOnlyProvenanceRejected
+    case provenanceIdentifierMismatch
+    case provenanceVersionMismatch
+    case provenanceBuildMismatch
+    case provenanceSourceMismatch
+    case provenanceTeamMismatch
+    case provenanceMinimumOSMismatch
+    case provenanceArchitectureMismatch
+    case provenanceCompanionVersionMismatch
+}
+
+/// Pure equality policy between candidate metadata and a verified release envelope.
+///
+/// Parsing, ownership, and file-stability checks remain at the broker I/O boundary.
+/// This policy runs before the broker enters monotonic state handling, so every
+/// semantic value used to identify a release must exactly equal signed evidence.
+public enum CandidateMetadataPolicy {
+    public static func validate(
+        application: CandidateApplicationMetadata,
+        updateClientArchitectures: [String],
+        companion: CandidateCompanionMetadata,
+        provenance: CandidateBuildProvenanceMetadata,
+        expected: CandidateReleaseMetadataExpectation
+    ) throws {
+        guard application.bundleIdentifier == expected.applicationIdentifier else {
+            throw CandidateMetadataPolicyError.applicationIdentifierMismatch
+        }
+        guard application.shortVersion == expected.version else {
+            throw CandidateMetadataPolicyError.applicationVersionMismatch
+        }
+        guard application.buildVersion == expected.build else {
+            throw CandidateMetadataPolicyError.applicationBuildMismatch
+        }
+        guard application.executable == expected.applicationExecutable else {
+            throw CandidateMetadataPolicyError.applicationExecutableMismatch
+        }
+        guard application.minimumOSVersion == expected.minimumOSVersion else {
+            throw CandidateMetadataPolicyError.applicationMinimumOSMismatch
+        }
+        guard application.architectures == expected.architectures else {
+            throw CandidateMetadataPolicyError.applicationArchitectureMismatch
+        }
+        guard updateClientArchitectures == expected.architectures else {
+            throw CandidateMetadataPolicyError.updateClientArchitectureMismatch
+        }
+        guard companion.architectures == expected.architectures else {
+            throw CandidateMetadataPolicyError.companionArchitectureMismatch
+        }
+        guard companion.sha256 == provenance.companionSHA256 else {
+            throw CandidateMetadataPolicyError.companionDigestMismatch
+        }
+
+        guard provenance.schemaVersion == 4 else {
+            throw CandidateMetadataPolicyError.provenanceSchemaMismatch
+        }
+        guard !provenance.containsLocalOnlyFields else {
+            throw CandidateMetadataPolicyError.localOnlyProvenanceRejected
+        }
+        guard provenance.bundleIdentifier == expected.applicationIdentifier else {
+            throw CandidateMetadataPolicyError.provenanceIdentifierMismatch
+        }
+        guard provenance.bundleVersion == expected.version else {
+            throw CandidateMetadataPolicyError.provenanceVersionMismatch
+        }
+        guard provenance.bundleBuildVersion == expected.build else {
+            throw CandidateMetadataPolicyError.provenanceBuildMismatch
+        }
+        guard provenance.sourceCommit == expected.sourceCommit else {
+            throw CandidateMetadataPolicyError.provenanceSourceMismatch
+        }
+        guard provenance.teamIdentifier == expected.signingTeamIdentifier else {
+            throw CandidateMetadataPolicyError.provenanceTeamMismatch
+        }
+        guard provenance.minimumMacOS == expected.minimumOSVersion else {
+            throw CandidateMetadataPolicyError.provenanceMinimumOSMismatch
+        }
+        // The release build contract requires the packaged companion's --version
+        // to equal the app release version before signing. At update time the
+        // broker binds that signed semantic assertion to the measured companion
+        // digest without executing candidate code as root.
+        guard provenance.companionVersion == provenance.bundleVersion,
+              provenance.companionVersion == expected.version
+        else {
+            throw CandidateMetadataPolicyError.provenanceCompanionVersionMismatch
+        }
+        guard provenance.architectures == expected.architectures,
+              provenance.companionArchitectures == expected.architectures
+        else {
+            throw CandidateMetadataPolicyError.provenanceArchitectureMismatch
+        }
+    }
+}

package/src/native/Recordings/Updater/Protocol/HostOSVersionPolicy.swift

@@ -0,0 +1,55 @@
+public enum HostOSVersionPolicyError: Error, Equatable, Sendable {
+    case hostProductVersionUnavailable
+    case malformedCandidateMinimumOSVersion
+    case malformedHostProductVersion
+    case candidateRequiresNewerOS
+}
+
+/// Pure compatibility policy for signed minimum-OS evidence and live host evidence.
+///
+/// macOS ProductVersion and LSMinimumSystemVersion commonly omit a zero patch
+/// component. Parse two- and three-component numeric versions, normalize the
+/// missing patch to zero, and never fall back to lexical comparison.
+public enum HostOSVersionPolicy {
+    public static func validate(
+        candidateMinimumOSVersion: String,
+        hostProductVersion: String?
+    ) throws {
+        guard let candidate = components(candidateMinimumOSVersion) else {
+            throw HostOSVersionPolicyError.malformedCandidateMinimumOSVersion
+        }
+        guard let hostProductVersion else {
+            throw HostOSVersionPolicyError.hostProductVersionUnavailable
+        }
+        guard let host = components(hostProductVersion) else {
+            throw HostOSVersionPolicyError.malformedHostProductVersion
+        }
+        guard !host.lexicographicallyPrecedes(candidate) else {
+            throw HostOSVersionPolicyError.candidateRequiresNewerOS
+        }
+    }
+
+    public static func isValidNumericVersion(_ value: String) -> Bool {
+        components(value) != nil
+    }
+
+    private static func components(_ value: String) -> [UInt64]? {
+        guard !value.isEmpty, value.utf8.count <= 64 else { return nil }
+        let fields = value.split(separator: ".", omittingEmptySubsequences: false)
+        guard fields.count == 2 || fields.count == 3 else { return nil }
+        var result: [UInt64] = []
+        result.reserveCapacity(3)
+        for field in fields {
+            guard !field.isEmpty,
+                  field.utf8.allSatisfy({ $0 >= 0x30 && $0 <= 0x39 }),
+                  (field.count == 1 || field.first != "0"),
+                  let component = UInt64(field)
+            else {
+                return nil
+            }
+            result.append(component)
+        }
+        if result.count == 2 { result.append(0) }
+        return result
+    }
+}

package/src/native/Recordings/Updater/Protocol/MonotonicReleasePolicy.swift

@@ -0,0 +1,152 @@
+import Foundation
+
+public enum MonotonicReleasePhase: String, Equatable, Sendable {
+    case seen
+    case aborted
+    case committed
+}
+
+public struct MonotonicReleaseCandidate: Equatable, Sendable {
+    public let purpose: String
+    public let keyEpoch: UInt64
+    public let releaseSequence: UInt64
+    public let releaseID: String
+    public let cohortPackageSHA256: String
+    public let envelopePayloadSHA256: String
+
+    public init(
+        purpose: String,
+        keyEpoch: UInt64,
+        releaseSequence: UInt64,
+        releaseID: String,
+        cohortPackageSHA256: String,
+        envelopePayloadSHA256: String
+    ) {
+        self.purpose = purpose
+        self.keyEpoch = keyEpoch
+        self.releaseSequence = releaseSequence
+        self.releaseID = releaseID
+        self.cohortPackageSHA256 = cohortPackageSHA256
+        self.envelopePayloadSHA256 = envelopePayloadSHA256
+    }
+}
+
+public struct MonotonicReleaseStateSnapshot: Equatable, Sendable {
+    public let purpose: String
+    public let phase: MonotonicReleasePhase
+    public let keyEpoch: UInt64
+    public let releaseSequence: UInt64
+    public let releaseID: String
+    public let cohortPackageSHA256: String
+    public let envelopePayloadSHA256: String
+
+    public init(
+        purpose: String,
+        phase: MonotonicReleasePhase,
+        keyEpoch: UInt64,
+        releaseSequence: UInt64,
+        releaseID: String,
+        cohortPackageSHA256: String,
+        envelopePayloadSHA256: String
+    ) {
+        self.purpose = purpose
+        self.phase = phase
+        self.keyEpoch = keyEpoch
+        self.releaseSequence = releaseSequence
+        self.releaseID = releaseID
+        self.cohortPackageSHA256 = cohortPackageSHA256
+        self.envelopePayloadSHA256 = envelopePayloadSHA256
+    }
+}
+
+public enum MonotonicReleasePolicyDecision: Equatable, Sendable {
+    case advance
+    case resumeSeen
+    case alreadyCommitted
+}
+
+public enum MonotonicReleasePolicyError: Error, Equatable, Sendable {
+    case immutableCohortChange
+    case bootstrapRequired
+    case bootstrapAlreadyInitialized
+    case sequenceRollbackOrConflict
+    case pendingSeenRecoveryRequired
+}
+
+/// Pure transition policy for the durable updater state machine.
+///
+/// A `seen` record is a recovery barrier: until its exact release commits or is
+/// durably aborted after exact-tree rollback, no
+/// other release may replace it, even when the other release has a higher
+/// sequence. An `aborted` record preserves the highest observed sequence while
+/// allowing only a strictly newer release from the same immutable cohort.
+public enum MonotonicReleasePolicy {
+    public static func assess(
+        candidate: MonotonicReleaseCandidate,
+        current: MonotonicReleaseStateSnapshot?,
+        initialKeyEpoch: UInt64,
+        allowedKeyEpochs: [UInt64]
+    ) throws -> MonotonicReleasePolicyDecision {
+        guard allowedKeyEpochs == [initialKeyEpoch],
+              candidate.keyEpoch == initialKeyEpoch
+        else {
+            throw MonotonicReleasePolicyError.immutableCohortChange
+        }
+
+        guard let current else {
+            guard candidate.purpose == "bootstrap" else {
+                throw MonotonicReleasePolicyError.bootstrapRequired
+            }
+            return .advance
+        }
+
+        guard current.keyEpoch == initialKeyEpoch else {
+            throw MonotonicReleasePolicyError.immutableCohortChange
+        }
+
+        let isExactReplay = candidate.purpose == current.purpose
+            && candidate.keyEpoch == current.keyEpoch
+            && candidate.releaseSequence == current.releaseSequence
+            && candidate.releaseID == current.releaseID
+            && candidate.cohortPackageSHA256 == current.cohortPackageSHA256
+            && candidate.envelopePayloadSHA256 == current.envelopePayloadSHA256
+
+        if current.phase == .seen {
+            guard isExactReplay else {
+                throw MonotonicReleasePolicyError.pendingSeenRecoveryRequired
+            }
+            return .resumeSeen
+        }
+
+        if current.phase == .aborted {
+            guard candidate.purpose != "bootstrap" else {
+                throw MonotonicReleasePolicyError.bootstrapAlreadyInitialized
+            }
+            guard candidate.cohortPackageSHA256 == current.cohortPackageSHA256 else {
+                throw MonotonicReleasePolicyError.immutableCohortChange
+            }
+            guard candidate.releaseSequence > current.releaseSequence else {
+                throw MonotonicReleasePolicyError.sequenceRollbackOrConflict
+            }
+            return .advance
+        }
+
+        if candidate.purpose == "bootstrap" {
+            guard current.purpose == "bootstrap", isExactReplay else {
+                throw MonotonicReleasePolicyError.bootstrapAlreadyInitialized
+            }
+            return .alreadyCommitted
+        }
+
+        guard candidate.cohortPackageSHA256 == current.cohortPackageSHA256 else {
+            throw MonotonicReleasePolicyError.immutableCohortChange
+        }
+        if isExactReplay {
+            return .alreadyCommitted
+        }
+        guard candidate.releaseSequence > current.releaseSequence else {
+            throw MonotonicReleasePolicyError.sequenceRollbackOrConflict
+        }
+        return .advance
+    }
+}