Run a virtual iPhone on an Apple Silicon Mac.
Swift
Count template users by build, and say what a delete frees
Jacky9a35217d13d6
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.mdindex 58c00f97..7d0e7cce 100644--- a/Documents/Guides/create-and-run.md+++ b/Documents/Guides/create-and-run.md@@ -152,12 +152,12 @@ vphone-cli vm template delete <id>- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.-- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:+- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks. `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:```note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7````-- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that still share its blocks, or that none does and its space is free now. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.+- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks, though a local Time Machine snapshot taken while it existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.## Manual stagesdiff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.mdindex df032de6..06ca1f42 100644--- a/Research/Host/machine_templates.md+++ b/Research/Host/machine_templates.md@@ -78,8 +78,11 @@ re-resolves with the template's own `PatchSelection.plist`.Launchpad never list a template.- `Template.plist`: `Identifier`, `Key`, `Created`, `BuiltWithBundleVersion`,`BootChainBundleVersion`, `SourceMachine` (the name a derived mDNS name- follows from), `Frozen`, `FrozenAt`, `Steps` (`SnapshotDeleted`,- `SetupDone`, `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`),+ follows from), `Frozen`, `FrozenAt`, `Build` (a UUID set each time a template+ is frozen or adopted), `Steps` (`SnapshotDeleted`, `SetupDone`,+ `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`, and+ `UnregisterAttempts`: the removed apps vphoned had to unregister more than+ once, with the count; not part of the key),`Sources` (`IPhone`, `CloudOS`: the IPSW sources a `vm create` build or`vm template adopt --iphone-source … --cloudos-source …` named; not part ofthe key). `vm template find` and `vm create` resolve a request's builds@@ -97,18 +100,34 @@ re-resolves with the template's own `PatchSelection.plist`.not found" for a deleted local IPSW (Launchpad 2.9 end-to-end test, B3 andB4).- `TemplateSource.plist` in a machine cloned from a template: `Identifier`,- `Cloned`. A plain `vm clone` keeps it (the copy shares the template's- blocks too); `vm export` excludes it (an import shares nothing).- `VPhoneMachineTemplates.usage` maps each template to the machines (and- templates adopted from such machines) that carry its identifier. `vm- template list/show` print it with the template's allocated size; `vm delete`- of the last machine using a template that still exists prints a note to- delete it (`unusedTemplate(after:in:)`), never deleting it itself.- `vm template delete` says what the deletion frees- (`VPhoneMachineTemplates.deletionNote`, from `usage` read before it): with- machines using the template, that they still share its blocks, freed only- when they change them or are deleted; with none, that its space is free- now. Until 2026-10-09 it printed the first note whatever the usage (B8).+ `Build` (the template's `Build`), `Cloned`. A plain `vm clone` keeps it+ (the copy shares the template's blocks too); `vm export` excludes it (an+ import shares nothing). `VPhoneMachineTemplates.usage` maps each template to+ the machines (and templates adopted from such machines) cloned from it.+ The identifier alone does not say that: a template deleted and built again+ with the same key gets the same identifier and shares nothing with the+ clones of the old one. A clone counts for a template only when+ `VPhoneMachineTemplateSource.isClone(of:)` says so: both `Build`s equal, or,+ when either side has none (records written before 2026-10-09), `Cloned` no+ earlier than the template's `FrozenAt` (else `Created`). Until then the+ rebuilt template counted the old build's clones as its users, in `vm+ template list/show`, Launchpad's "N machine(s) use it" and the delete notes+ (PR #633 retest, N1). `vm template list/show --json` add `build` and+ `frozenAt`. `vm template list/show` print the users with the template's+ allocated size; `vm delete` of the last machine cloned from the template+ that exists now prints a note to delete it (`unusedTemplate(after:in:)`;+ deleting a clone of an earlier build prints nothing), never deleting it+ itself. `vm template delete` says what the deletion frees+ (`VPhoneMachineTemplates.deletionNote`, from `usage` read before it), from+ facts it has: with machines using the template, it names them and says the+ blocks they share stay allocated until they change them or are deleted;+ with none, "no machine uses it now; deleting frees its blocks (a local Time+ Machine snapshot may keep them until it expires)". It cannot know whether+ the template was cloned before and the clones deleted, so it no longer says+ "no machine was cloned from it", and a local snapshot can keep the blocks,+ so it no longer says "its space is free now" (retest B8). `--json` (with+ `--force`) prints `deleted`, `path`, `machines`, `blocksFreed` and the+ same `note`.- A build happens in `.building-<id>-<uuid>/<id>/` and is frozen by writing`Frozen = true` and one `renamex_np(RENAME_EXCL)` to `.templates/<id>`. Alisted template is always complete; a race with another build of the same@@ -410,7 +429,15 @@ nine removed apps, `adopt` saved the template under a key `vm template find`never computes for the default options, and every later create with themmissed it and built another 17.5 GB template (B1). vphoned now polls therecord every 0.1 s for up to 2.5 s, unregisters once more if it is still-listed, and only then fails the app (`GuestAppUnregistration`). For Launchpad+listed, and only then fails the app (`GuestAppUnregistration`). It+reports `unregister_attempts` for an app that needed more than one call. The+setup boot keeps it (`VPhoneTemplateSetupAppResult.unregisterAttempts`),+prints ` <bundle id>: unregistered after N attempts` in its remove-apps step+and a summary line in its report, and records the counts in+`Steps.UnregisterAttempts`, so the race can be counted from build logs and+`vm template show`. Until 2026-10-09 the count never left vphoned (retest+G1). It does not tell a first check that still saw the app from one that did+not: an app that left LaunchServices while vphoned polled still counts 1. For Launchpadthe setup boot is meant to run with `--strict` and the adopt with`--expect <id>` (below), so a template is never saved under a key the requestdid not ask for.diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swiftindex 898533aa..4ccecf50 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift@@ -189,6 +189,10 @@ enum VPhoneTemplateSetupRun {}print(" services: \(services)\(outcome.serviceProfile == "none" ? "" : " (\(outcome.servicesOwned) owned)")")print(" apps removed: \(outcome.removedApps.isEmpty ? "none" : outcome.removedApps.joined(separator: ", "))")+ let retried = outcome.retriedUnregistrations.sorted { $0.key < $1.key }+ if !retried.isEmpty {+ print(" unregistered after retries: \(retried.map { "\($0.key) (\($0.value) attempts)" }.joined(separator: ", "))")+ }for warning in outcome.warnings {print(" warning: \(warning)")}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swiftindex 0ba58b00..1435513b 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift@@ -56,12 +56,18 @@ struct VPhoneMachineTemplateReport: Encodable {/// What the template's files take on disk (`st_blocks`): what deleting/// it frees once no machine shares its blocks.var allocatedBytes: UInt64- /// Machines cloned from it (their `TemplateSource.plist`), sorted.+ /// Machines cloned from this build of it (their `TemplateSource.plist`),+ /// sorted. Machines cloned from an earlier template with the same key+ /// are not listed: they share none of its blocks.var machines: [String]var stale: Boolvar staleReasons: [String]/// The IPSW sources it was built from, when its build named them.var sources: VPhoneMachineTemplateSources?+ /// The build's UUID, copied into each clone's `TemplateSource.plist`;+ /// nil for a template frozen before builds were recorded.+ var build: String?+ var frozenAt: Date?init(_ template: VPhoneMachineTemplate, usage: [String: [String]]) {let record = template.record@@ -79,6 +85,8 @@ struct VPhoneMachineTemplateReport: Encodable {staleReasons = VPhoneMachineTemplateKeys.staleReasons(template)stale = !staleReasons.isEmptysources = record.sources+ build = record.build+ frozenAt = record.frozenAt}}@@ -180,7 +188,14 @@ struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {print("removed: \(key.slimming.removedApps.joined(separator: ","))")}print("steps: snapshot deleted \(report.steps.snapshotDeleted ? "yes" : "no"), setup done \(report.steps.setupDone ? "yes" : "no")")+ let retried = report.steps.unregisterAttempts.sorted { $0.key < $1.key }+ if !retried.isEmpty {+ print("retried: \(retried.map { "\($0.key) unregistered after \($0.value) attempts" }.joined(separator: ", "))")+ }print("created: \(report.created.formatted(.iso8601))")+ if let frozenAt = report.frozenAt {+ print("frozen: \(frozenAt.formatted(.iso8601))\(report.build.map { ", build \($0)" } ?? "")")+ }if let source = report.sourceMachine {print("source: \(source)")}@@ -709,13 +724,24 @@ struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {abstract: "Delete a template or an unfinished template build",discussion: """Machines cloned from the template keep working: they share its blocks but do not refer \- to it. The space those shared blocks take is freed only when no clone uses them either.+ to it. The space those shared blocks take is freed only when no clone uses them either. \+ A local Time Machine snapshot taken while the template existed keeps its blocks until \+ the snapshot expires.++ --json prints what was deleted and the machines that used it; it needs --force.""",)@OptionGroup var lib: VPhoneLibraryOption@Argument(help: "template id (or unique prefix), or a .building-… name from vm template list") var id: String@Flag(name: .shortAndLong, help: "Do not prompt") var force = false+ @Flag(name: .shortAndLong, help: "Emit the result as JSON (needs --force)") var json = false++ func validate() throws {+ if json, !force {+ throw ValidationError("--json does not prompt: pass --force with it.")+ }+ }func run() throws {let library = lib.library@@ -733,7 +759,33 @@ struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {let identifier = (try? VPhoneMachineTemplates.template(id, in: library).identifier) ?? idlet machines = id.hasPrefix(".building-") ? [] : VPhoneMachineTemplates.usage(in: library)[identifier] ?? []let removed = try VPhoneMachineTemplates.delete(id, in: library)+ let note = VPhoneMachineTemplates.deletionNote(machines: machines)+ if json {+ try print(encodeJSON(VPhoneMachineTemplateDeleteReport(+ deleted: removed.lastPathComponent,+ path: removed.path,+ machines: machines,+ blocksFreed: machines.isEmpty,+ note: note,+ )))+ return+ }print("deleted \(removed.lastPathComponent)")- print("note: \(VPhoneMachineTemplates.deletionNote(machines: machines))")+ print("note: \(note)")}}++/// What `vm template delete --json` prints.+struct VPhoneMachineTemplateDeleteReport: Encodable {+ /// The template identifier or `.building-…` name removed.+ var deleted: String+ var path: String+ /// The machines that used the template when it was deleted; their shared+ /// blocks stay allocated until they change them or are deleted.+ var machines: [String]+ /// True when no machine used it, so its blocks are freed, unless a local+ /// Time Machine snapshot keeps them until it expires.+ var blocksFreed: Bool+ /// The same note the text output prints.+ var note: String+}diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swiftindex 09cd37da..89374da2 100644--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift@@ -20,6 +20,11 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {public var serviceGroups: [String]public var removedApps: [String]public var trimTier: String+ /// The removed apps vphoned had to unregister more than once, with the+ /// number of attempts. Not part of the key: a record of how the setup+ /// boot went, kept so the race with first-boot registration can be+ /// counted afterwards.+ public var unregisterAttempts: [String: Int]public init(snapshotDeleted: Bool = false,@@ -28,6 +33,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {serviceGroups: [String] = [],removedApps: [String] = [],trimTier: String = "none",+ unregisterAttempts: [String: Int] = [:],) {self.snapshotDeleted = snapshotDeletedself.setupDone = setupDone@@ -35,6 +41,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {self.serviceGroups = Array(Set(serviceGroups)).sorted()self.removedApps = Array(Set(removedApps)).sorted()self.trimTier = trimTier+ self.unregisterAttempts = unregisterAttempts}/// Why a template with these steps must not be frozen, or nothing.@@ -74,6 +81,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {case serviceGroups = "ServiceGroups"case removedApps = "RemovedApps"case trimTier = "TrimTier"+ case unregisterAttempts = "UnregisterAttempts"}public init(from decoder: any Decoder) throws {@@ -84,6 +92,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {serviceGroups = try container.decodeIfPresent([String].self, forKey: .serviceGroups) ?? []removedApps = try container.decodeIfPresent([String].self, forKey: .removedApps) ?? []trimTier = try container.decodeIfPresent(String.self, forKey: .trimTier) ?? "none"+ unregisterAttempts = try container.decodeIfPresent([String: Int].self, forKey: .unregisterAttempts) ?? [:]}}@@ -91,17 +100,42 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {/// `TemplateSource.plist`, in a machine cloned from a template: which/// template it shares blocks with.+///+/// The identifier names a key, and a key outlives any one template built for+/// it: a template deleted and built again gets the same identifier, but the+/// new one shares no block with machines cloned from the old one. `Build`+/// names the build, so only machines of the template that exists now count+/// as its users.public struct VPhoneMachineTemplateSource: Codable, Equatable, Sendable {public var identifier: String+ /// The ``VPhoneMachineTemplateRecord/build`` of the template it was cloned+ /// from; nil in a record written before builds had one, or for a+ /// template without one.+ public var build: String?public var cloned: Date- public init(identifier: String, cloned: Date = Date()) {+ public init(identifier: String, build: String? = nil, cloned: Date = Date()) {self.identifier = identifier+ self.build = buildself.cloned = VPhoneMachineTemplates.wholeSeconds(cloned)}+ /// Whether a machine with this record was cloned from the template+ /// `record` describes, and not from an earlier one with the same key.+ /// Both sides having a build decides it. Otherwise (a record written+ /// before builds were recorded, on either side) the dates do: a machine+ /// cloned before the template was frozen cannot have come from it.+ public func isClone(of record: VPhoneMachineTemplateRecord) -> Bool {+ guard identifier == record.identifier else { return false }+ if let build, let other = record.build {+ return build == other+ }+ return cloned >= (record.frozenAt ?? record.created)+ }+private enum CodingKeys: String, CodingKey {case identifier = "Identifier"+ case build = "Build"case cloned = "Cloned"}}@@ -182,6 +216,12 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {/// template adopted without them. Not part of the key: two URLs of the/// same build make the same template.public var sources: VPhoneMachineTemplateSources?+ /// A UUID set each time a template is frozen or adopted, and copied into+ /// each clone's `TemplateSource.plist`. The identifier stays the same+ /// when a template is deleted and built again; this does not, so the+ /// clones of an earlier build are not counted as the new one's users.+ /// Nil for a template frozen before it was recorded.+ public var build: String?public init(key: VPhoneMachineTemplateKey,@@ -193,6 +233,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {frozenAt: Date? = nil,steps: VPhoneMachineTemplateSteps = VPhoneMachineTemplateSteps(),sources: VPhoneMachineTemplateSources? = nil,+ build: String? = nil,) {identifier = key.identifierself.key = key@@ -204,6 +245,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {self.frozenAt = frozenAt.map(VPhoneMachineTemplates.wholeSeconds)self.steps = stepsself.sources = sources+ self.build = build}private enum CodingKeys: String, CodingKey {@@ -217,6 +259,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {case frozenAt = "FrozenAt"case steps = "Steps"case sources = "Sources"+ case build = "Build"}public init(from decoder: any Decoder) throws {@@ -231,6 +274,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {frozenAt = try container.decodeIfPresent(Date.self, forKey: .frozenAt)steps = try container.decodeIfPresent(VPhoneMachineTemplateSteps.self, forKey: .steps) ?? VPhoneMachineTemplateSteps()sources = try container.decodeIfPresent(VPhoneMachineTemplateSources.self, forKey: .sources)+ build = try container.decodeIfPresent(String.self, forKey: .build)}}@@ -669,6 +713,7 @@ public enum VPhoneMachineTemplates {try removeRestoreTree(of: bundle)record.frozen = truerecord.frozenAt = Self.wholeSeconds(now)+ record.build = UUID().uuidStringtry writeRecord(record, inBundle: build.bundleURL)let destination = url(of: build.identifier, in: build.libraryRoot)do {@@ -677,6 +722,7 @@ public enum VPhoneMachineTemplates {} catch {record.frozen = falserecord.frozenAt = nil+ record.build = niltry? writeRecord(record, inBundle: build.bundleURL)throw error}@@ -747,6 +793,7 @@ public enum VPhoneMachineTemplates {try removeRestoreTree(of: bundle)record.frozen = truerecord.frozenAt = Self.wholeSeconds(now)+ record.build = UUID().uuidStringtry writeRecord(record, inBundle: bundle.url)do {// Checked again just before the rename: nothing may have opened@@ -788,7 +835,10 @@ public enum VPhoneMachineTemplates {newIdentity: true,)do {- try writeSource(VPhoneMachineTemplateSource(identifier: template.identifier), inBundle: clone.url)+ try writeSource(+ VPhoneMachineTemplateSource(identifier: template.identifier, build: template.record.build),+ inBundle: clone.url,+ )} catch {try? FileManager.default.removeItem(at: clone.url)throw error@@ -827,27 +877,46 @@ public enum VPhoneMachineTemplates {/// The machines of the library cloned from each template, by template/// identifier, sorted by name. Templates adopted from such a machine/// count too, under `.templates/<id>`: they share its blocks as well.+ ///+ /// A machine counts only for the template it was cloned from+ /// (``VPhoneMachineTemplateSource/isClone(of:)``): one cloned from an+ /// earlier template with the same key, since deleted and built again,+ /// shares nothing with the template that exists now and is left out. A+ /// machine whose template no longer exists is listed under its identifier.public static func usage(in library: VPhoneLibrary) -> [String: [String]] {+ let templates = (try? list(in: library).templates) ?? []+ var records: [String: VPhoneMachineTemplateRecord] = [:]+ for template in templates {+ records[template.identifier] = template.record+ }var users: [String: [String]] = [:]+ func count(_ source: VPhoneMachineTemplateSource, as user: String) {+ if let record = records[source.identifier], !source.isClone(of: record) {+ return+ }+ users[source.identifier, default: []].append(user)+ }for bundle in (try? library.bundles()) ?? [] {if let source = readSource(inBundle: bundle.url) {- users[source.identifier, default: []].append(bundle.name)+ count(source, as: bundle.name)}}- for template in (try? list(in: library).templates) ?? [] {+ for template in templates {if let source = readSource(inBundle: template.url), source.identifier != template.identifier {- users[source.identifier, default: []].append("\(directoryName)/\(template.identifier)")+ count(source, as: "\(directoryName)/\(template.identifier)")}}return users.mapValues { $0.sorted() }}- /// The template `source` names, when it still exists and nothing in the- /// library uses it any more: what `vm delete` reports after deleting a- /// machine cloned from it. Never deletes it.+ /// The template `source` names, when it still exists, the deleted machine+ /// was cloned from it (not from an earlier template with the same key),+ /// and nothing in the library uses it any more: what `vm delete` reports+ /// after deleting a machine cloned from it. Never deletes it.public static func unusedTemplate(after source: VPhoneMachineTemplateSource?, in library: VPhoneLibrary) -> VPhoneMachineTemplate? {guard let source,let template = try? Self.template(source.identifier, in: library),+ source.isClone(of: template.record),usage(in: library)[template.identifier, default: []].isEmptyelse { return nil }return template@@ -886,17 +955,20 @@ public enum VPhoneMachineTemplates {// MARK: Delete- /// What `vm template delete` says about the space it freed: blocks a- /// machine cloned from the template still shares stay allocated until- /// that machine changes or is deleted; with no such machine, the- /// template's space is free at once. `machines` is what- /// ``usage(in:)`` listed for the template before it was deleted.+ /// What `vm template delete` says about the space it freed, from what is+ /// known. `machines` is what ``usage(in:)`` listed for the template before+ /// it was deleted: the machines that use it now. Machines cloned from it+ /// and deleted since are not among them, so the note never claims it was+ /// never cloned. With no user its blocks are freed, unless a local Time+ /// Machine snapshot taken while it existed keeps them; with users, the+ /// blocks they share stay allocated until they change them or are deleted.public static func deletionNote(machines: [String]) -> String {guard !machines.isEmpty else {- return "no machine was cloned from it, so its space is free now"+ return "no machine uses it now; deleting frees its blocks "+ + "(a local Time Machine snapshot may keep them until it expires)"}- return "\(machines.count) machine(s) cloned from it (\(machines.joined(separator: ", "))) still share its blocks; "- + "those blocks are freed only when the machines change them or are deleted"+ return "\(machines.count) machine(s) use it (\(machines.joined(separator: ", "))); "+ + "the blocks they share with it stay allocated until they change them or are deleted"}/// Removes a frozen template, by identifier or unique prefix, or a stagingdiff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swiftindex 5bfaa8af..c986e468 100644--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift@@ -194,11 +194,17 @@ public struct VPhoneTemplateSetupAppResult: Equatable, Sendable {/// vphoned's status: `removed`, `absent`, `unregistered_stale` or `failed`.public var status: Stringpublic var error: String?+ /// How many times vphoned called LaunchServices to unregister the app:+ /// more than one when the app was still listed after the first call (the+ /// race with Find My's first-boot registration). vphoned reports it only+ /// above one; 1 otherwise.+ public var unregisterAttempts: Int- public init(bundleID: String, status: String, error: String? = nil) {+ public init(bundleID: String, status: String, error: String? = nil, unregisterAttempts: Int = 1) {self.bundleID = bundleIDself.status = statusself.error = error+ self.unregisterAttempts = unregisterAttempts}/// The app is not installed afterwards, whichever way.@@ -230,6 +236,16 @@ public struct VPhoneTemplateSetupOutcome: Equatable, Sendable {apps.filter(\.isGone).map(\.bundleID).sorted()}+ /// The apps vphoned had to unregister more than once, with the number of+ /// attempts.+ public var retriedUnregistrations: [String: Int] {+ var retried: [String: Int] = [:]+ for app in apps where app.unregisterAttempts > 1 {+ retried[app.bundleID] = app.unregisterAttempts+ }+ return retried+ }+/// Where the slimming done so far falls short of `plan`: an app not/// removed, another service profile or groups. What a strict setup boot/// refuses once the profile is applied.@@ -264,6 +280,7 @@ public struct VPhoneTemplateSetupOutcome: Equatable, Sendable {steps.serviceProfile = serviceProfilesteps.serviceGroups = serviceGroups.sorted()steps.removedApps = removedApps+ steps.unregisterAttempts = retriedUnregistrationsreturn steps}}@@ -457,7 +474,12 @@ public final class VPhoneTemplateSetupBoot {}var results = rows.compactMap { row -> VPhoneTemplateSetupAppResult? inguard let id = row["bundle_id"] as? String else { return nil }- return VPhoneTemplateSetupAppResult(bundleID: id, status: row["status"] as? String ?? "failed", error: row["error"] as? String)+ return VPhoneTemplateSetupAppResult(+ bundleID: id,+ status: row["status"] as? String ?? "failed",+ error: row["error"] as? String,+ unregisterAttempts: max(1, Self.number(row["unregister_attempts"]).flatMap { Int(exactly: $0.rounded()) } ?? 1),+ )}for id in plan.removedApps where !results.contains(where: { $0.bundleID == id }) {results.append(VPhoneTemplateSetupAppResult(bundleID: id, status: "failed", error: "vphoned returned no result for it"))@@ -465,6 +487,12 @@ public final class VPhoneTemplateSetupBoot {outcome.apps = resultslet refused = results.filter { !$0.isGone }log(" \(results.count - refused.count) of \(results.count) apps removed or absent")+ // Each app LaunchServices still listed after the first unregister+ // call: the build log is where the race with first-boot+ // registration can be counted.+ for app in results.sorted(by: { $0.bundleID < $1.bundleID }) where app.unregisterAttempts > 1 {+ log(" \(app.bundleID): unregistered after \(app.unregisterAttempts) attempts")+ }guard !refused.isEmpty else { return }let lines = refused.map { "\($0.bundleID): \($0.error ?? $0.status)" }if plan.requiresEveryApp {diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swiftindex 1364780d..2fed51c4 100644--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift@@ -663,10 +663,124 @@ struct MachineTemplatesTests {}}- @Test func `deleting a template says the space is free unless machines still share its blocks`() {- #expect(VPhoneMachineTemplates.deletionNote(machines: []) == "no machine was cloned from it, so its space is free now")+ @Test func `deleting a template says its blocks are freed unless machines use it`() {+ let free = VPhoneMachineTemplates.deletionNote(machines: [])+ #expect(free.hasPrefix("no machine uses it now; deleting frees its blocks"))+ // Never claims it was never cloned, and does not promise free space a+ // local Time Machine snapshot may keep.+ #expect(!free.contains("cloned"))+ #expect(free.contains("Time Machine snapshot"))let shared = VPhoneMachineTemplates.deletionNote(machines: ["phone-a", "phone-b"])- #expect(shared.hasPrefix("2 machine(s) cloned from it (phone-a, phone-b) still share its blocks"))- #expect(shared.contains("freed only when"))+ #expect(shared.hasPrefix("2 machine(s) use it (phone-a, phone-b); "))+ #expect(shared.contains("stay allocated until they change them or are deleted"))+ }++ // MARK: - Builds++ @Test func `a template rebuilt with the same key does not count the old build's clones`() throws {+ let fixture = try makeFixture()+ defer { fixture.cleanUp() }+ try makeMachine("src", in: fixture)+ let first = try VPhoneMachineTemplates.adopt(+ machineNamed: "src", in: fixture.library, record: record(), now: Date(timeIntervalSince1970: 1_800_000_100),+ )+ let firstBuild = try #require(first.record.build)+ let old = try VPhoneMachineTemplates.cloneMachine(from: first, to: "old", in: fixture.library)+ #expect(VPhoneMachineTemplates.readSource(inBundle: old.url)?.build == firstBuild)+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])++ // Deleted and built again under the same identifier, with a new build.+ try VPhoneMachineTemplates.delete(first.identifier, in: fixture.library)+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])+ try makeMachine("src2", in: fixture)+ let second = try VPhoneMachineTemplates.adopt(machineNamed: "src2", in: fixture.library, record: record(source: "src2"))+ #expect(second.identifier == first.identifier)+ #expect(second.record.build != nil && second.record.build != firstBuild)+ #expect(VPhoneMachineTemplates.usage(in: fixture.library)[second.identifier] == nil)++ let new = try VPhoneMachineTemplates.cloneMachine(from: second, to: "new", in: fixture.library)+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [second.identifier: ["new"]])+ // Deleting the old build's clone says nothing about the new template;+ // deleting the new one's last clone does.+ let oldSource = VPhoneMachineTemplates.readSource(inBundle: old.url)+ try VPhoneBundleOperations.delete(bundleNamed: "old", in: fixture.library)+ #expect(VPhoneMachineTemplates.unusedTemplate(after: oldSource, in: fixture.library) == nil)+ let newSource = VPhoneMachineTemplates.readSource(inBundle: new.url)+ try VPhoneBundleOperations.delete(bundleNamed: "new", in: fixture.library)+ #expect(VPhoneMachineTemplates.unusedTemplate(after: newSource, in: fixture.library)?.identifier == second.identifier)+ }++ @Test func `a clone record without a build is matched by its clone date`() throws {+ let frozenAt = Date(timeIntervalSince1970: 1_800_000_100)+ var template = record()+ template.frozen = true+ template.frozenAt = frozenAt+ template.build = UUID().uuidString+ let id = template.identifier++ // Written before builds were recorded: the date decides.+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt).isClone(of: template))+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt + 60).isClone(of: template))+ #expect(!VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt - 1).isClone(of: template))+ // A build on both sides decides, whatever the dates say.+ #expect(VPhoneMachineTemplateSource(identifier: id, build: template.build, cloned: frozenAt - 600).isClone(of: template))+ #expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: template))+ // A template frozen before builds were recorded: the date again.+ var legacy = template+ legacy.build = nil+ #expect(VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: legacy))+ #expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt - 60).isClone(of: legacy))+ // Without a freeze date, the creation date.+ legacy.frozenAt = nil+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: template.created).isClone(of: legacy))+ #expect(!VPhoneMachineTemplateSource(identifier: id, cloned: template.created - 1).isClone(of: legacy))+ // Another key never.+ #expect(!VPhoneMachineTemplateSource(identifier: "000000000000", build: template.build, cloned: frozenAt).isClone(of: template))+ }++ @Test func `a legacy clone record of a deleted template is left out by date`() throws {+ let fixture = try makeFixture()+ defer { fixture.cleanUp() }+ try makeMachine("src", in: fixture)+ let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())+ let frozenAt = try #require(template.record.frozenAt)+ // Two clones whose records predate builds: one of an earlier template+ // with this key, one of this one.+ let earlier = try makeMachine("earlier", in: fixture)+ try VPhoneMachineTemplates.writeSource(+ VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt - 3600), inBundle: earlier.url,+ )+ let current = try makeMachine("current", in: fixture)+ try VPhoneMachineTemplates.writeSource(+ VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt + 1), inBundle: current.url,+ )+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [template.identifier: ["current"]])+ }++ @Test func `a record without a build reads, and a frozen one gets one`() throws {+ let fixture = try makeFixture()+ defer { fixture.cleanUp() }+ let machine = try makeMachine("src", in: fixture)+ // An older record: no Build key at all.+ try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)+ let raw = try Data(contentsOf: machine.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName))+ #expect(!String(decoding: raw, as: UTF8.self).contains("<key>Build</key>"))+ #expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.build == nil)+ let source = try PropertyListDecoder().decode(+ VPhoneMachineTemplateSource.self,+ from: PropertyListSerialization.data(+ fromPropertyList: ["Identifier": "52b1fcc75e0c", "Cloned": Date(timeIntervalSince1970: 1_800_000_000)],+ format: .xml, options: 0,+ ),+ )+ #expect(source.build == nil)++ let key = MachineTemplateKeyTests.key(bootChain: "built")+ let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)+ try makeMachine(key.identifier, in: fixture, library: build.library)+ try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)+ let frozen = try VPhoneMachineTemplates.freeze(build)+ #expect(frozen.record.build != nil)+ #expect(try VPhoneMachineTemplates.template(frozen.identifier, in: fixture.library).record.build == frozen.record.build)}}diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swiftindex 6e7c98cd..0ab9d8fe 100644--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift@@ -34,6 +34,8 @@ private final class FakeGuest: VPhoneTemplateSetupMachine {var skipFailures = 0var unsettledAnswers = 1var refusedApps: Set<String> = []+ /// Apps vphoned had to unregister more than once, as it reports them.+ var unregisterAttempts: [String: Int] = [:]var servicesKeepRunning = falsevar rebootNeverReturns = falsevar stopsCleanly = true@@ -124,7 +126,9 @@ private final class FakeGuest: VPhoneTemplateSetupMachine {if refusedApps.contains(id) {results.append(["bundle_id": id, "status": "failed", "removed": false, "error": "not in a bundle container"])} else if installed.remove(id) != nil {- results.append(["bundle_id": id, "status": "removed", "removed": true])+ var row: [String: Any] = ["bundle_id": id, "status": "removed", "removed": true]+ row["unregister_attempts"] = unregisterAttempts[id]+ results.append(row)} else {results.append(["bundle_id": id, "status": "absent", "removed": false])}@@ -405,6 +409,34 @@ struct TemplateSetupBootTests {#expect(outcome.removedApps.contains("com.apple.news"))}+ @Test func `apps unregistered after more than one attempt are logged and recorded`() throws {+ let guest = FakeGuest(clock: FakeClock())+ guest.unregisterAttempts = ["com.apple.findmy": 3, "com.apple.tv": 2]+ var lines: [String] = []+ let boot = VPhoneTemplateSetupBoot(+ machine: guest,+ plan: VPhoneTemplateSetupPlan(slimming: VPhoneTemplateSlimmingRequest.defaultSlimming, requiresEveryApp: true),+ clock: guest.clock,+ log: { lines.append($0) },+ )+ let outcome = try boot.run()++ #expect(outcome.apps.first(where: { $0.bundleID == "com.apple.findmy" })?.unregisterAttempts == 3)+ #expect(outcome.apps.first(where: { $0.bundleID == "com.apple.news" })?.unregisterAttempts == 1)+ #expect(outcome.retriedUnregistrations == ["com.apple.findmy": 3, "com.apple.tv": 2])+ #expect(lines.contains(" com.apple.findmy: unregistered after 3 attempts"))+ #expect(lines.contains(" com.apple.tv: unregistered after 2 attempts"))+ #expect(!lines.contains { $0.contains("com.apple.news: unregistered") })+ // Recorded with the steps, outside the key.+ let steps = outcome.applying(to: VPhoneMachineTemplateSteps())+ #expect(steps.unregisterAttempts == ["com.apple.findmy": 3, "com.apple.tv": 2])+ var without = steps+ without.unregisterAttempts = [:]+ #expect(without.slimming == steps.slimming)+ let encoded = try PropertyListEncoder().encode(steps)+ #expect(try PropertyListDecoder().decode(VPhoneMachineTemplateSteps.self, from: encoded) == steps)+ }+@Test func `a VM that exits fails the step it was in`() throws {let guest = FakeGuest(clock: FakeClock())guest.exitsAfterStart = true