@adea-ai/app-framework 0.39.3 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/README.md +160 -53
  2. package/dist/app/application.d.ts +0 -1
  3. package/dist/app/application.js +8 -6
  4. package/dist/app/create-application.js +3 -11
  5. package/dist/app/service-registry.d.ts +0 -1
  6. package/dist/app/service-registry.js +3 -3
  7. package/dist/app/value-guards.d.ts +2 -0
  8. package/dist/app/value-guards.js +6 -1
  9. package/dist/appearance/appearance-host.d.ts +1 -1
  10. package/dist/appearance/appearance-host.js +11 -2
  11. package/dist/appearance/appearance-preferences.d.ts +0 -1
  12. package/dist/appearance/custom-theme-import.d.ts +8 -2
  13. package/dist/appearance/custom-theme-import.js +58 -23
  14. package/dist/appearance/custom-theme-library.d.ts +3 -3
  15. package/dist/appearance/custom-theme-library.js +3 -3
  16. package/dist/appearance/theme-file-importer.d.ts +1 -1
  17. package/dist/appearance/theme-file-importer.js +2 -1
  18. package/dist/appearance/theme-library-mutation.d.ts +7 -0
  19. package/dist/appearance/theme-library-mutation.js +10 -2
  20. package/dist/appearance/theme-library-store.d.ts +17 -13
  21. package/dist/appearance/theme-library-store.js +35 -22
  22. package/dist/appearance/theme-record-adapter.js +1 -2
  23. package/dist/appearance/theme-registry.js +0 -1
  24. package/dist/cli/cli-runner.d.ts +3 -2
  25. package/dist/cli/cli-runner.js +5 -10
  26. package/dist/cli/release-assets-plan-cli.js +2 -2
  27. package/dist/cli/release-cut-cli.js +2 -3
  28. package/dist/cli/release-descriptor-staging-cli.js +2 -2
  29. package/dist/cli/release-finalize-cli.js +3 -3
  30. package/dist/cli/release-promote-cli.js +2 -2
  31. package/dist/cli/release-publish-cli.js +2 -2
  32. package/dist/cli/release-sign-cli.js +2 -1
  33. package/dist/cli/release-step-cli.js +2 -2
  34. package/dist/desktop/channel-proof.js +27 -11
  35. package/dist/desktop/client-assets.d.ts +6 -1
  36. package/dist/desktop/client-assets.js +16 -3
  37. package/dist/desktop/client-dev-proxy.d.ts +0 -2
  38. package/dist/desktop/client-dev-proxy.js +2 -2
  39. package/dist/desktop/desktop-client.js +2 -1
  40. package/dist/desktop/desktop-gateway.js +24 -82
  41. package/dist/desktop/desktop-host-websocket.d.ts +5 -1
  42. package/dist/desktop/desktop-host-websocket.js +9 -7
  43. package/dist/desktop/desktop-host.d.ts +5 -0
  44. package/dist/desktop/desktop-host.js +3 -0
  45. package/dist/desktop/desktop-stream.js +5 -10
  46. package/dist/desktop/typed-array-intrinsics.d.ts +6 -0
  47. package/dist/desktop/typed-array-intrinsics.js +13 -1
  48. package/dist/developer-app/developer-app.d.ts +1 -1
  49. package/dist/developer-app/developer-app.js +26 -13
  50. package/dist/framework-source.json +1 -1
  51. package/dist/installer/command-artifact.d.ts +1 -0
  52. package/dist/installer/command-artifact.js +47 -27
  53. package/dist/installer/installed-payload.js +3 -1
  54. package/dist/installer/installer-ci-bootstrap.js +5 -6
  55. package/dist/installer/installer-ci-preflight.js +3 -3
  56. package/dist/installer/installer-identity.d.ts +0 -22
  57. package/dist/installer/installer-identity.js +3 -53
  58. package/dist/installer/installer-image-mount.d.ts +0 -1
  59. package/dist/installer/installer-image-mount.js +1 -1
  60. package/dist/installer/installer-observation.d.ts +5 -5
  61. package/dist/installer/installer-observation.js +32 -47
  62. package/dist/installer/installer-process-cleanup.js +2 -2
  63. package/dist/installer/installer-renderer-evidence.js +7 -28
  64. package/dist/installer/installer-upgrade-command.js +8 -20
  65. package/dist/installer/installer-worker-guard.js +3 -3
  66. package/dist/native/cef-helper.js +4 -4
  67. package/dist/native/desktop-build.d.ts +0 -3
  68. package/dist/native/desktop-build.js +2 -2
  69. package/dist/native/electrobun-source-patch.d.ts +4 -0
  70. package/dist/native/electrobun-source-patch.js +5 -1
  71. package/dist/native/native-utilities.js +4 -3
  72. package/dist/native/pinned-download.d.ts +16 -0
  73. package/dist/native/pinned-download.js +42 -0
  74. package/dist/native/posix-launcher-build.js +15 -35
  75. package/dist/native/posix-tree-removal.js +21 -33
  76. package/dist/native/sidecar-services.d.ts +0 -2
  77. package/dist/native/sidecar-services.js +1 -1
  78. package/dist/native/sidecar.d.ts +3 -0
  79. package/dist/native/sidecar.js +15 -2
  80. package/dist/native/window-surface-store.js +3 -3
  81. package/dist/native/windows-extractor-build.d.ts +6 -16
  82. package/dist/native/windows-extractor-build.js +11 -14
  83. package/dist/release/feed-release-cut.d.ts +2 -6
  84. package/dist/release/feed-release-cut.js +5 -93
  85. package/dist/release/feed-state.js +1 -5
  86. package/dist/release/github-release-cut.js +5 -66
  87. package/dist/release/github-release-provenance.d.ts +2 -0
  88. package/dist/release/github-release-provenance.js +4 -7
  89. package/dist/release/github-release-publisher.js +2 -2
  90. package/dist/release/github-release-qualification.js +3 -3
  91. package/dist/release/local-release.d.ts +3 -3
  92. package/dist/release/local-release.js +12 -23
  93. package/dist/release/qualification-run.js +1 -1
  94. package/dist/release/release-assets-plan.js +1 -1
  95. package/dist/release/release-config.d.ts +7 -15
  96. package/dist/release/release-config.js +25 -29
  97. package/dist/release/release-cut-command.d.ts +1 -1
  98. package/dist/release/release-cut-command.js +1 -1
  99. package/dist/release/release-cut.d.ts +5 -32
  100. package/dist/release/release-cut.js +9 -55
  101. package/dist/release/release-descriptor-staging.js +3 -8
  102. package/dist/release/release-promotion.js +2 -1
  103. package/dist/release/release-publish-command.js +5 -15
  104. package/dist/release/release-qualification.js +1 -1
  105. package/dist/shared/bounded-body.d.ts +33 -0
  106. package/dist/shared/bounded-body.js +102 -0
  107. package/dist/shared/file-system.d.ts +12 -0
  108. package/dist/shared/file-system.js +40 -0
  109. package/dist/shell/app-shell.js +29 -14
  110. package/dist/shell/app-utilities.d.ts +4 -1
  111. package/dist/shell/app-utilities.js +5 -1
  112. package/dist/shell/application-menu.d.ts +1 -1
  113. package/dist/shell/application-menu.js +7 -3
  114. package/dist/shell/poll.d.ts +27 -0
  115. package/dist/shell/poll.js +88 -0
  116. package/dist/update-helper.bundle.js +268 -144
  117. package/dist/updates/channel-update-manager.js +0 -1
  118. package/dist/updates/desktop-updater.d.ts +9 -0
  119. package/dist/updates/desktop-updater.js +103 -50
  120. package/dist/updates/feed/release-feed.d.ts +7 -4
  121. package/dist/updates/feed/release-feed.js +3 -7
  122. package/dist/updates/feed/release-location.js +6 -26
  123. package/dist/updates/feed/release-version.d.ts +7 -2
  124. package/dist/updates/feed/release-version.js +9 -2
  125. package/dist/updates/feed/signed-release.d.ts +1 -1
  126. package/dist/updates/feed/signed-release.js +2 -2
  127. package/dist/updates/feed/update-discovery.js +2 -6
  128. package/dist/updates/helper/launch-gate-recovery.js +28 -78
  129. package/dist/updates/helper/resume-staging.d.ts +14 -3
  130. package/dist/updates/helper/resume-staging.js +23 -37
  131. package/dist/updates/helper/update-helper.d.ts +6 -2
  132. package/dist/updates/helper/update-helper.js +38 -33
  133. package/dist/updates/helper/update-resume.js +9 -6
  134. package/dist/updates/install/update-extraction.js +28 -8
  135. package/dist/updates/install/update-handoff-plan.d.ts +0 -1
  136. package/dist/updates/install/update-handoff-plan.js +3 -4
  137. package/dist/updates/install/update-swap-stage.js +1 -6
  138. package/dist/updates/install/update-swap.d.ts +5 -2
  139. package/dist/updates/install/update-swap.js +193 -72
  140. package/dist/updates/launch/helper-exit-wait.d.ts +6 -0
  141. package/dist/updates/launch/helper-exit-wait.js +18 -0
  142. package/dist/updates/launch/packaged-update-startup.js +8 -6
  143. package/dist/updates/launch/update-launch-gate.js +7 -14
  144. package/dist/updates/locks/stable-file.js +4 -1
  145. package/dist/updates/locks/update-helper-presence.d.ts +12 -0
  146. package/dist/updates/locks/update-helper-presence.js +27 -0
  147. package/dist/updates/retention/retention-cleanup.js +10 -9
  148. package/dist/updates/retention/retention-maintenance.d.ts +40 -0
  149. package/dist/updates/retention/retention-maintenance.js +95 -0
  150. package/dist/updates/retention/retention-prune-progress.js +4 -5
  151. package/dist/updates/retention/retirement-inventory.d.ts +13 -0
  152. package/dist/updates/retention/retirement-inventory.js +39 -31
  153. package/dist/updates/retention/retirement-records.d.ts +1 -4
  154. package/dist/updates/retention/retirement-records.js +18 -32
  155. package/dist/updates/retention/update-retention-marker.d.ts +4 -0
  156. package/dist/updates/retention/update-retention-marker.js +9 -14
  157. package/dist/updates/retention/update-retirement.d.ts +12 -0
  158. package/dist/updates/retention/update-retirement.js +59 -31
  159. package/dist/updates/update-adapter.d.ts +1 -23
  160. package/dist/updates/update-adapter.js +31 -24
  161. package/dist/updates/update-channel-store.d.ts +2 -1
  162. package/dist/updates/update-channel-store.js +6 -4
  163. package/dist/updates/update-manager.js +2 -2
  164. package/dist/updates/update-services.d.ts +1 -1
  165. package/dist/updates/update-services.js +9 -4
  166. package/dist/updates/update-state-store.d.ts +0 -2
  167. package/dist/updates/update-state-store.js +5 -12
  168. package/dist/updates/update-state.d.ts +6 -10
  169. package/dist/updates/update-state.js +1 -1
  170. package/dist/views/app-help.d.ts +1 -1
  171. package/dist/views/app-help.js +1 -3
  172. package/dist/views/appearance-surface.js +15 -8
  173. package/dist/views/update-surface.d.ts +1 -3
  174. package/dist/views/update-surface.js +2 -2
  175. package/package.json +20 -18
  176. package/src/app/application.tsx +13 -6
  177. package/src/appearance/appearance-host.tsx +17 -7
  178. package/src/appearance/appearance-preferences.ts +0 -1
  179. package/src/appearance/custom-theme-import.ts +99 -26
  180. package/src/appearance/custom-theme-library.ts +3 -2
  181. package/src/appearance/theme-file-importer.ts +3 -2
  182. package/src/appearance/theme-library-mutation.ts +20 -8
  183. package/src/appearance/theme-library-schema.ts +7 -0
  184. package/src/appearance/theme-library-store.ts +41 -26
  185. package/src/desktop/client-assets.ts +27 -12
  186. package/src/shell/app-shell.tsx +33 -13
  187. package/src/shell/app-utilities.tsx +10 -1
  188. package/src/shell/poll.ts +125 -0
  189. package/src/updates/feed/release-version.ts +11 -3
  190. package/src/updates/update-adapter.ts +27 -44
  191. package/src/updates/update-state.ts +7 -13
  192. package/src/views/app-help.tsx +1 -1
  193. package/src/views/appearance-surface.tsx +36 -8
  194. package/src/views/update-surface.tsx +0 -4
  195. package/templates/application/.github/workflows/release-assets.yml +2 -2
  196. package/templates/application/README.md +3 -3
  197. package/dist/native/cef-helper-download.d.ts +0 -1
  198. package/dist/native/cef-helper-download.js +0 -35
  199. package/src/desktop/client-response-lifecycle.ts +0 -305
@@ -0,0 +1,40 @@
1
+ import { type UpdateRetentionPruneStep } from './retention-cleanup';
2
+ export type RetiredUpdatePruneResult = Readonly<{
3
+ /** `clean`: nothing older than the rollback tree is left; `more`: the run's bound was hit. */
4
+ status: 'clean' | 'more' | 'busy' | 'unsupported' | 'recovery-required';
5
+ pruned: number;
6
+ }>;
7
+ type PruneOperations = {
8
+ begin(options: {
9
+ target: string;
10
+ currentVersion: string;
11
+ }): Promise<{
12
+ intent: {
13
+ generation: string;
14
+ };
15
+ } | null>;
16
+ step(options: {
17
+ target: string;
18
+ currentVersion: string;
19
+ generation: string;
20
+ maxOperations: number;
21
+ }): Promise<UpdateRetentionPruneStep>;
22
+ publishedIntents(target: string): Promise<string[]>;
23
+ supported(): boolean;
24
+ };
25
+ /**
26
+ * Remove retired app trees older than the rollback tree, oldest first, keeping the
27
+ * installed tree and the one it replaced. Finishes a prune an earlier run left behind
28
+ * before starting a new one. Every step revalidates under the install lock and the
29
+ * generation's exclusive lease, so a tree an instance still leases reports `busy` and is
30
+ * left for a later run; anything unexpected stops with `recovery-required` and changes
31
+ * nothing further. Steps are bounded and yield to the event loop between them.
32
+ */
33
+ export declare function pruneRetiredUpdates(options: {
34
+ target: string;
35
+ currentVersion: string;
36
+ /** Bound on generations removed in one run. */
37
+ maxGenerations?: number;
38
+ operations?: Partial<PruneOperations>;
39
+ }): Promise<RetiredUpdatePruneResult>;
40
+ export {};
@@ -0,0 +1,95 @@
1
+ import { beginUpdateRetentionCleanup, pruneUpdateRetentionStep } from "./retention-cleanup.js";
2
+ import { readdir } from "node:fs/promises";
3
+ import { basename, dirname } from "node:path";
4
+ // src/updates/retention/retention-maintenance.ts
5
+ var INTENT_FILE = /^([\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12})\.json$/;
6
+ /** Generations whose prune intent an earlier run published but did not finish. */
7
+ async function publishedIntents(target) {
8
+ const prefix = `.${basename(target)}.framework-prune-`;
9
+ return (await readdir(dirname(target))).flatMap((name) => {
10
+ if (!name.startsWith(prefix)) return [];
11
+ const match = INTENT_FILE.exec(name.slice(prefix.length));
12
+ return match ? [match[1]] : [];
13
+ });
14
+ }
15
+ var defaultOperations = {
16
+ begin: beginUpdateRetentionCleanup,
17
+ step: pruneUpdateRetentionStep,
18
+ publishedIntents,
19
+ supported: () => process.platform === "darwin" && process.arch === "arm64"
20
+ };
21
+ /**
22
+ * Remove retired app trees older than the rollback tree, oldest first, keeping the
23
+ * installed tree and the one it replaced. Finishes a prune an earlier run left behind
24
+ * before starting a new one. Every step revalidates under the install lock and the
25
+ * generation's exclusive lease, so a tree an instance still leases reports `busy` and is
26
+ * left for a later run; anything unexpected stops with `recovery-required` and changes
27
+ * nothing further. Steps are bounded and yield to the event loop between them.
28
+ */
29
+ async function pruneRetiredUpdates(options) {
30
+ const operations = {
31
+ ...defaultOperations,
32
+ ...options.operations
33
+ };
34
+ const { target, currentVersion } = options;
35
+ const maxGenerations = options.maxGenerations ?? 16;
36
+ if (!operations.supported()) return {
37
+ status: "unsupported",
38
+ pruned: 0
39
+ };
40
+ let pruned = 0;
41
+ const drain = async (generation) => {
42
+ for (;;) {
43
+ const step = await operations.step({
44
+ target,
45
+ currentVersion,
46
+ generation,
47
+ maxOperations: 1024
48
+ });
49
+ if (step.status === "pruned") return "pruned";
50
+ if (step.status === "none") return "none";
51
+ if (step.status !== "more") return step.status;
52
+ await new Promise((resolve) => setTimeout(resolve, 0));
53
+ }
54
+ };
55
+ try {
56
+ for (const generation of await operations.publishedIntents(target)) {
57
+ const outcome = await drain(generation);
58
+ if (outcome === "pruned") pruned++;
59
+ else if (outcome !== "none") return {
60
+ status: outcome,
61
+ pruned
62
+ };
63
+ }
64
+ while (pruned < maxGenerations) {
65
+ const begun = await operations.begin({
66
+ target,
67
+ currentVersion
68
+ });
69
+ if (!begun) return {
70
+ status: "clean",
71
+ pruned
72
+ };
73
+ const outcome = await drain(begun.intent.generation);
74
+ if (outcome === "none") return {
75
+ status: "recovery-required",
76
+ pruned
77
+ };
78
+ if (outcome !== "pruned") return {
79
+ status: outcome,
80
+ pruned
81
+ };
82
+ pruned++;
83
+ }
84
+ return {
85
+ status: "more",
86
+ pruned
87
+ };
88
+ } catch {
89
+ return {
90
+ status: "recovery-required",
91
+ pruned
92
+ };
93
+ }
94
+ }
95
+ export { pruneRetiredUpdates };
@@ -1,10 +1,9 @@
1
- import { isUuid } from "../../app/value-guards.js";
1
+ import { hasExactOwnKeys, isUuid } from "../../app/value-guards.js";
2
2
  import { syncDarwinDescriptor } from "../../native/darwin-sync.js";
3
- import { retentionIdentityKey } from "./update-retention-plan.js";
4
- import { sameRetentionIntent, updateRetentionIntentPath } from "./update-retention-marker.js";
3
+ import { isTreeIdentity, sameRetentionIntent, updateRetentionIntentPath } from "./update-retention-marker.js";
5
4
  import { sameUpdateTreeIdentity } from "../install/update-swap.js";
6
5
  import { readSmallStateFile } from "../locks/stable-file.js";
7
- import { hasExactOwnKeys, healthReceiptFor, healthReceiptMatches, ownerMatches, parseHealthReceipt, parseOwner, pathInfo, readHealthReceipt, readOwner, updateRetirementPaths } from "./retirement-records.js";
6
+ import { healthReceiptFor, healthReceiptMatches, ownerMatches, parseHealthReceipt, parseOwner, pathInfo, readHealthReceipt, readOwner, updateRetirementPaths } from "./retirement-records.js";
8
7
  import { link, lstat, open, readdir, rename, unlink, writeFile } from "node:fs/promises";
9
8
  import { basename, dirname, join } from "node:path";
10
9
  import { randomUUID } from "node:crypto";
@@ -75,7 +74,7 @@ async function readPruneProgressFile(path, target, generation, expectedIntent, e
75
74
  "installedTreeIdentity"
76
75
  ]) || expectedIntent !== void 0 && !sameRetentionIntent(record.intent, expectedIntent) || typeof record.owner !== "object" || record.owner === null || Array.isArray(record.owner)) return void 0;
77
76
  const intent = record.intent;
78
- if (intent.schema !== 1 || intent.phase !== "prune-previous-tree" || typeof intent.target !== "string" || intent.target !== target || typeof intent.generation !== "string" || intent.generation !== generation.toLowerCase() || !retentionIdentityKey(intent.previousTreeIdentity) || !retentionIdentityKey(intent.installedTreeIdentity) || typeof intent.installedGeneration !== "string" || !isUuid(intent.installedGeneration) || Object.keys(intent.previousTreeIdentity).length !== 2 || !hasExactOwnKeys(intent.previousTreeIdentity, ["device", "inode"]) || Object.keys(intent.installedTreeIdentity).length !== 2 || !hasExactOwnKeys(intent.installedTreeIdentity, ["device", "inode"])) return void 0;
77
+ if (intent.schema !== 1 || intent.phase !== "prune-previous-tree" || typeof intent.target !== "string" || intent.target !== target || typeof intent.generation !== "string" || intent.generation !== generation.toLowerCase() || !isTreeIdentity(intent.previousTreeIdentity) || !isTreeIdentity(intent.installedTreeIdentity) || typeof intent.installedGeneration !== "string" || !isUuid(intent.installedGeneration)) return void 0;
79
78
  const owner = parseOwner(record.owner);
80
79
  if (!owner || expectedOwner && !ownerMatches(owner, expectedOwner)) return void 0;
81
80
  const healthReceipt = parseHealthReceipt(record.healthReceipt);
@@ -25,6 +25,19 @@ export type RetainedUpdateTrees = Readonly<{
25
25
  trees: readonly RetainedUpdateTree[];
26
26
  release(): Promise<void>;
27
27
  }>;
28
+ /**
29
+ * Read and validate every retirement claim and container while the install lock
30
+ * is held. Retention planning can opt into rejecting in-progress cleanup and
31
+ * receipt publication artifacts; acknowledgement discovery preserves its
32
+ * existing support for those recoverable receipt temporaries.
33
+ */
34
+ export declare function readValidatedRetirementInventoryWhileLocked(target: string, currentVersion: string, options?: Readonly<{
35
+ strictRetentionState?: boolean;
36
+ allowedRetentionIntentGeneration?: string;
37
+ allowedRetentionTemporaryName?: string;
38
+ allowedPruneProgressGeneration?: string;
39
+ allowedPruneProgressTemporaryName?: string;
40
+ }>): Promise<ValidatedRetirementInventory>;
28
41
  /**
29
42
  * Discover the exact unacknowledged installed generation after staging cleanup.
30
43
  * The generation claim is persistent beside the retired tree, so discovery does
@@ -1,19 +1,22 @@
1
- import { isUuid } from "../../app/value-guards.js";
1
+ import { errorCode, isUuid } from "../../app/value-guards.js";
2
2
  import { hasUpdateHelperArtifacts } from "../helper/update-helper.js";
3
3
  import { tryAcquireUpdateGenerationLease } from "../locks/update-generation-lease.js";
4
- import { updateProcessMayBeAlive } from "../locks/update-process-liveness.js";
4
+ import { recordedUpdateHelperMayBeRunning } from "../locks/update-helper-presence.js";
5
5
  import { readUpdateLaunchGate, tryAcquireUpdateHelperLiveness } from "../launch/update-launch-gate.js";
6
6
  import { verifyReleaseDescriptor } from "../feed/signed-release.js";
7
7
  import { planUpdateRetention, retentionIdentityKey } from "./update-retention-plan.js";
8
8
  import { readUpdateRetentionIntent, updateRetentionIntentPath } from "./update-retention-marker.js";
9
9
  import { readUpdateStageState, withUpdateLock } from "../update-state-store.js";
10
- import { readUpdateTreeDigest, readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeDigest, sameUpdateTreeIdentity, updateStagingFor } from "../install/update-swap.js";
10
+ import { createTaskLimiter, readUpdateTreeDigest, readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeDigest, sameUpdateTreeIdentity, updateStagingFor } from "../install/update-swap.js";
11
11
  import { isCanonicalPath } from "../../native/canonical-path.js";
12
12
  import { assertNoUnresolvedRetentionPruneArtifacts, isPruneProgressName, pruneProgressNames, readPruneProgress, readPruneProgressFile, retentionPruneProgressPath } from "./retention-prune-progress.js";
13
- import { VERSION, generationFromClaimName, healthReceiptMatches, matchesInstalledTree, matchesOwnedTree, matchesPartiallyPrunedContainer, ownerMatches, pathInfo, readHealthReceipt, readOwner, updateRetirementPaths, validRetirementContainer } from "./retirement-records.js";
13
+ import { generationFromClaimName, healthReceiptMatches, matchesInstalledTree, matchesOwnedTree, matchesPartiallyPrunedContainer, ownerMatches, pathInfo, readHealthReceipt, readOwner, updateRetirementPaths, validRetirementContainer } from "./retirement-records.js";
14
+ import { isReleaseVersion } from "../feed/release-version.js";
14
15
  import { lstat, readdir } from "node:fs/promises";
15
16
  import { basename, dirname, join } from "node:path";
16
17
  // src/updates/retention/retirement-inventory.ts
18
+ /** Retirement records validated at once while the install lock is held. */
19
+ var RECORD_CONCURRENCY = 8;
17
20
  /**
18
21
  * Read and validate every retirement claim and container while the install lock
19
22
  * is held. Retention planning can opt into rejecting in-progress cleanup and
@@ -22,10 +25,12 @@ import { basename, dirname, join } from "node:path";
22
25
  */
23
26
  async function readValidatedRetirementInventoryWhileLocked(target, currentVersion, options = {}) {
24
27
  const strictRetentionState = options.strictRetentionState === true;
25
- const targetInfo = await pathInfo(target);
26
- const actualVersion = targetInfo?.isDirectory() ? await readUpdateTreeVersion(target) : void 0;
27
- const actualIdentity = targetInfo?.isDirectory() ? await readUpdateTreeIdentity(target) : void 0;
28
- if (!targetInfo?.isDirectory() || targetInfo.isSymbolicLink() || actualVersion !== currentVersion || !actualIdentity) throw new Error("The installed update does not match the host version");
28
+ const actualVersion = await readUpdateTreeVersion(target);
29
+ const actualIdentity = actualVersion === currentVersion ? await readUpdateTreeIdentity(target).catch((error) => {
30
+ if (errorCode(error) === "ENOENT") return void 0;
31
+ throw error;
32
+ }) : void 0;
33
+ if (actualVersion !== currentVersion || !actualIdentity) throw new Error("The installed update does not match the host version");
29
34
  const names = await readdir(dirname(target));
30
35
  const retirementPrefix = `.${basename(target)}.framework-retired-`;
31
36
  const cleanupMarkerName = `.${basename(target)}.framework-update-cleanup.json`;
@@ -92,26 +97,31 @@ async function readValidatedRetirementInventoryWhileLocked(target, currentVersio
92
97
  throw new Error("An unknown update retirement entry requires recovery");
93
98
  }
94
99
  for (const generation of containerGenerations) if (!claimNames.has(basename(updateRetirementPaths(target, generation).claim)) && generation.toLowerCase() !== pruneProgress?.intent.generation) throw new Error("An update retirement container has no matching claim");
95
- const records = [];
96
- for (const name of claimNames) {
100
+ const readRecord = async (name) => {
97
101
  const generation = generationFromClaimName(name, target);
98
102
  if (!generation) {
99
103
  if (name.endsWith(".claim.json")) throw new Error("An update retirement claim has an invalid generation");
100
- continue;
104
+ return;
101
105
  }
102
106
  const paths = updateRetirementPaths(target, generation);
103
- if (name !== basename(paths.claim)) continue;
104
- if (pruneProgress?.intent.generation === generation.toLowerCase()) continue;
107
+ if (name !== basename(paths.claim)) return void 0;
108
+ if (pruneProgress?.intent.generation === generation.toLowerCase()) return void 0;
105
109
  const claimInfo = await pathInfo(paths.claim);
106
110
  const owner = await readOwner(paths.claim);
107
111
  if (!claimInfo?.isFile() || claimInfo.isSymbolicLink() || !owner || owner.target !== target || owner.generation !== generation) throw new Error("An update retirement claim requires recovery");
108
112
  const recordProgress = pruneProgress && owner.generation.toLowerCase() === pruneProgress.intent.generation ? pruneProgress : void 0;
109
113
  if (recordProgress && !ownerMatches(owner, recordProgress.owner) || !await validRetirementContainer(owner, paths, !strictRetentionState, recordProgress)) throw new Error("An update retirement container requires recovery");
110
- records.push({
114
+ return {
111
115
  owner,
112
116
  paths,
113
117
  healthy: Boolean(await pathInfo(paths.healthReceipt))
114
- });
118
+ };
119
+ };
120
+ const limit = createTaskLimiter(RECORD_CONCURRENCY);
121
+ const records = [];
122
+ for (const outcome of await Promise.allSettled([...claimNames].map((name) => limit(() => readRecord(name))))) {
123
+ if (outcome.status === "rejected") throw outcome.reason;
124
+ if (outcome.value) records.push(outcome.value);
115
125
  }
116
126
  if (pruneProgressTemporary && !pruneProgress) {
117
127
  const record = records.find(({ owner }) => owner.generation.toLowerCase() === pruneProgressTemporary.intent.generation);
@@ -156,14 +166,14 @@ async function readValidatedRetirementInventoryWhileLocked(target, currentVersio
156
166
  */
157
167
  async function findPendingUpdateHealthAcknowledgement(options) {
158
168
  const { target, currentVersion } = options;
159
- if (typeof currentVersion !== "string" || !VERSION.test(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid update health acknowledgement lookup");
169
+ if (typeof currentVersion !== "string" || !isReleaseVersion(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid update health acknowledgement lookup");
160
170
  return withUpdateLock(target, async () => {
161
171
  const staging = updateStagingFor(target);
162
172
  const stagingInfo = await pathInfo(staging);
163
173
  if (stagingInfo) {
164
174
  if (!stagingInfo.isDirectory() || stagingInfo.isSymbolicLink()) return null;
165
175
  const state = await readUpdateStageState(staging);
166
- if (state?.helperPid && updateProcessMayBeAlive(state.helperPid)) return null;
176
+ if (state && await recordedUpdateHelperMayBeRunning(target, state)) return null;
167
177
  if ((!state || !state.helperPid) && await hasUpdateHelperArtifacts(staging)) return null;
168
178
  }
169
179
  const inventory = await readValidatedRetirementInventoryWhileLocked(target, currentVersion);
@@ -199,7 +209,7 @@ async function assertNoUpdateRetentionPruneArtifactsWhileLocked(target) {
199
209
  */
200
210
  async function planValidatedUpdateRetention(options) {
201
211
  const { target, currentVersion } = options;
202
- if (typeof currentVersion !== "string" || !VERSION.test(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid update retention lookup");
212
+ if (typeof currentVersion !== "string" || !isReleaseVersion(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid update retention lookup");
203
213
  return withUpdateLock(target, async () => (await planRetentionWhileLocked(target, currentVersion)).plan);
204
214
  }
205
215
  async function planRetentionWhileLocked(target, currentVersion, options = {}) {
@@ -228,10 +238,7 @@ async function planRetentionWhileLocked(target, currentVersion, options = {}) {
228
238
  allowedPruneProgressTemporaryName: options.allowedPruneProgressTemporaryName
229
239
  });
230
240
  const head = inventory.records.filter((record) => sameUpdateTreeIdentity(record.owner.newTreeIdentity, inventory.actualIdentity));
231
- if (head.length === 1) {
232
- const current = head[0].owner;
233
- if (current.newVersion !== inventory.actualVersion || !await matchesInstalledTree(target, current)) throw new Error("An installed update retirement record requires recovery");
234
- }
241
+ if (head.length === 1 && head[0].owner.newVersion !== inventory.actualVersion) throw new Error("An installed update retirement record requires recovery");
235
242
  const byInstalledIdentity = /* @__PURE__ */ new Map();
236
243
  for (const { owner } of inventory.records) {
237
244
  const key = retentionIdentityKey(owner.newTreeIdentity);
@@ -262,7 +269,7 @@ async function planRetentionWhileLocked(target, currentVersion, options = {}) {
262
269
  */
263
270
  async function acquireRetainedUpdateTrees(options) {
264
271
  const { target, currentVersion } = options;
265
- if (typeof currentVersion !== "string" || !VERSION.test(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid retained update tree lookup");
272
+ if (typeof currentVersion !== "string" || !isReleaseVersion(currentVersion) || !isCanonicalPath(target)) throw new Error("Invalid retained update tree lookup");
266
273
  let retained;
267
274
  try {
268
275
  return await withUpdateLock(target, async () => {
@@ -321,17 +328,18 @@ async function acquireRetainedUpdateTreesWhileLocked(options) {
321
328
  const b = right.owner.generation.toLowerCase();
322
329
  return a < b ? -1 : a > b ? 1 : 0;
323
330
  });
324
- for (const { owner, paths } of ordered) {
331
+ for (const { owner } of ordered) {
325
332
  const lease = await tryAcquireUpdateGenerationLease(target, owner.generation, "shared");
326
333
  if (!lease) return { status: "busy" };
327
334
  held.push(lease);
328
- if (!await matchesOwnedTree(paths.tree, owner)) throw new Error("A retained update tree changed during lease acquisition");
329
- trees.push(Object.freeze({
330
- generation: owner.generation,
331
- version: owner.previousVersion,
332
- tree: paths.tree
333
- }));
334
335
  }
336
+ const limit = createTaskLimiter(RECORD_CONCURRENCY);
337
+ if ((await Promise.all(ordered.map(({ owner, paths }) => limit(() => matchesOwnedTree(paths.tree, owner))))).includes(false)) throw new Error("A retained update tree changed during lease acquisition");
338
+ for (const { owner, paths } of ordered) trees.push(Object.freeze({
339
+ generation: owner.generation,
340
+ version: owner.previousVersion,
341
+ tree: paths.tree
342
+ }));
335
343
  return {
336
344
  status: "acquired",
337
345
  trees: Object.freeze(trees)
@@ -372,4 +380,4 @@ async function acquireRetainedUpdateTreesWhileLocked(options) {
372
380
  await helperLiveness?.release();
373
381
  }
374
382
  }
375
- export { acquireRetainedUpdateTrees, acquireRetainedUpdateTreesWhileLocked, assertNoUpdateRetentionPruneArtifactsWhileLocked, findPendingUpdateHealthAcknowledgement, planRetentionWhileLocked, planValidatedUpdateRetention };
383
+ export { acquireRetainedUpdateTrees, acquireRetainedUpdateTreesWhileLocked, assertNoUpdateRetentionPruneArtifactsWhileLocked, findPendingUpdateHealthAcknowledgement, planRetentionWhileLocked, planValidatedUpdateRetention, readValidatedRetirementInventoryWhileLocked };
@@ -1,4 +1,4 @@
1
- import type { UpdateRetentionIntent } from './update-retention-marker';
1
+ import { type UpdateRetentionIntent } from './update-retention-marker';
2
2
  import type { UpdateStageState } from '../update-state-store';
3
3
  import { type UpdateTreeIdentity } from '../install/update-swap';
4
4
  import type { RetentionPruneProgress } from './retention-prune-progress';
@@ -32,9 +32,6 @@ type RetirementCleanupMarker = Readonly<{
32
32
  claim: string;
33
33
  phase: 'staging-cleanup';
34
34
  }>;
35
- export declare const VERSION: RegExp;
36
- export declare const PUBLISHER_TEMP_UUID: RegExp;
37
- export declare function hasExactOwnKeys(value: Record<string, unknown>, expected: readonly string[]): boolean;
38
35
  /** Generation-specific retirement paths, all beside the fixed staging path. */
39
36
  export declare function updateRetirementPaths(target: string, generation: string): Readonly<{
40
37
  container: string;
@@ -1,18 +1,14 @@
1
- import { errorCode, isUuid } from "../../app/value-guards.js";
1
+ import { errorCode, hasExactOwnKeys, isUuid } from "../../app/value-guards.js";
2
2
  import { renameExclusive } from "../../native/native-rename.js";
3
+ import { isTreeIdentity } from "./update-retention-marker.js";
3
4
  import { readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeIdentity } from "../install/update-swap.js";
4
5
  import { isCanonicalPath } from "../../native/canonical-path.js";
5
6
  import { readSmallStateFile } from "../locks/stable-file.js";
7
+ import { isReleaseVersion } from "../feed/release-version.js";
6
8
  import { lstat, readdir, writeFile } from "node:fs/promises";
7
9
  import { basename, dirname, join } from "node:path";
8
10
  import { randomUUID } from "node:crypto";
9
11
  // src/updates/retention/retirement-records.ts
10
- var VERSION = /^\d+\.\d+\.\d+(?:-dev\.\d+)?$/;
11
- var PUBLISHER_TEMP_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
12
- function hasExactOwnKeys(value, expected) {
13
- const actual = Reflect.ownKeys(value);
14
- return actual.length === expected.length && actual.every((key) => typeof key === "string" && expected.includes(key));
15
- }
16
12
  /** Generation-specific retirement paths, all beside the fixed staging path. */
17
13
  function updateRetirementPaths(target, generation) {
18
14
  if (!isCanonicalPath(target) || !isUuid(generation)) throw new Error("Invalid update retirement identity");
@@ -69,9 +65,7 @@ function ownerFor(target, state) {
69
65
  function parseOwner(value) {
70
66
  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
71
67
  const record = value;
72
- const identity = record.previousTreeIdentity;
73
- const newTreeIdentity = record.newTreeIdentity;
74
- if (record.schema !== 2 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.newVersion !== "string" || !VERSION.test(record.newVersion) || typeof record.previousVersion !== "string" || !VERSION.test(record.previousVersion) || typeof identity !== "object" || identity === null || Array.isArray(identity) || !hasExactOwnKeys(identity, ["device", "inode"]) || typeof identity.device !== "string" || !/^[1-9]\d{0,19}$/.test(identity.device) || typeof identity.inode !== "string" || !/^[1-9]\d{0,19}$/.test(identity.inode) || typeof newTreeIdentity !== "object" || newTreeIdentity === null || Array.isArray(newTreeIdentity) || !hasExactOwnKeys(newTreeIdentity, ["device", "inode"]) || typeof newTreeIdentity.device !== "string" || !/^[1-9]\d{0,19}$/.test(newTreeIdentity.device) || typeof newTreeIdentity.inode !== "string" || !/^[1-9]\d{0,19}$/.test(newTreeIdentity.inode) || typeof record.container !== "string" || record.container !== `.${basename(record.target)}.framework-retired-${record.generation}` || record.tree !== "tree" || !hasExactOwnKeys(record, [
68
+ if (record.schema !== 2 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.newVersion !== "string" || !isReleaseVersion(record.newVersion) || typeof record.previousVersion !== "string" || !isReleaseVersion(record.previousVersion) || !isTreeIdentity(record.previousTreeIdentity) || !isTreeIdentity(record.newTreeIdentity) || typeof record.container !== "string" || record.container !== `.${basename(record.target)}.framework-retired-${record.generation}` || record.tree !== "tree" || !hasExactOwnKeys(record, [
75
69
  "schema",
76
70
  "generation",
77
71
  "target",
@@ -104,7 +98,7 @@ function cleanupMarkerMatches(actual, expected) {
104
98
  function parseCleanupMarker(value) {
105
99
  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
106
100
  const record = value;
107
- if (record.schema !== 1 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.version !== "string" || !VERSION.test(record.version) || typeof record.claim !== "string" || record.claim !== basename(updateRetirementPaths(record.target, record.generation).claim) || record.phase !== "staging-cleanup" || Object.keys(record).length !== 6) return void 0;
101
+ if (record.schema !== 1 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.version !== "string" || !isReleaseVersion(record.version) || typeof record.claim !== "string" || record.claim !== basename(updateRetirementPaths(record.target, record.generation).claim) || record.phase !== "staging-cleanup" || Object.keys(record).length !== 6) return void 0;
108
102
  return record;
109
103
  }
110
104
  async function readOwner(path) {
@@ -118,8 +112,7 @@ async function readOwner(path) {
118
112
  function parseHealthReceipt(value) {
119
113
  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
120
114
  const record = value;
121
- const identity = record.treeIdentity;
122
- if (record.schema !== 1 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.version !== "string" || !VERSION.test(record.version) || typeof identity !== "object" || identity === null || Array.isArray(identity) || !hasExactOwnKeys(identity, ["device", "inode"]) || typeof identity.device !== "string" || !/^[1-9]\d{0,19}$/.test(identity.device) || typeof identity.inode !== "string" || !/^[1-9]\d{0,19}$/.test(identity.inode) || !hasExactOwnKeys(record, [
115
+ if (record.schema !== 1 || typeof record.generation !== "string" || !isUuid(record.generation) || !isCanonicalPath(record.target) || typeof record.version !== "string" || !isReleaseVersion(record.version) || !isTreeIdentity(record.treeIdentity) || !hasExactOwnKeys(record, [
123
116
  "schema",
124
117
  "generation",
125
118
  "target",
@@ -164,15 +157,18 @@ async function pathInfo(path) {
164
157
  throw error;
165
158
  }
166
159
  }
167
- async function matchesOldTree(path, state) {
168
- if (!state.previousTreeIdentity) return false;
160
+ /** A real directory at `path` whose version marker and device/inode both match. */
161
+ async function treeMatches(path, version, identity) {
169
162
  try {
170
- const info = await lstat(path);
171
- return info.isDirectory() && !info.isSymbolicLink() && await readUpdateTreeVersion(path) === state.previousVersion && sameUpdateTreeIdentity(await readUpdateTreeIdentity(path), state.previousTreeIdentity);
163
+ return await readUpdateTreeVersion(path) === version && sameUpdateTreeIdentity(await readUpdateTreeIdentity(path), identity);
172
164
  } catch {
173
165
  return false;
174
166
  }
175
167
  }
168
+ async function matchesOldTree(path, state) {
169
+ if (!state.previousTreeIdentity) return false;
170
+ return treeMatches(path, state.previousVersion, state.previousTreeIdentity);
171
+ }
176
172
  function isMatchingClaimTemporary(name, paths) {
177
173
  if (!name.startsWith(paths.claimTemporaryPrefix) || !name.endsWith(".tmp")) return false;
178
174
  return isUuid(name.slice(paths.claimTemporaryPrefix.length, -4));
@@ -258,21 +254,11 @@ async function ensureCleanupMarker(target, state) {
258
254
  }
259
255
  return cleanupMarkerMatches(await readCleanupMarker(paths.cleanupMarker), expected);
260
256
  }
261
- async function matchesOwnedTree(path, owner) {
262
- try {
263
- const info = await lstat(path);
264
- return info.isDirectory() && !info.isSymbolicLink() && await readUpdateTreeVersion(path) === owner.previousVersion && sameUpdateTreeIdentity(await readUpdateTreeIdentity(path), owner.previousTreeIdentity);
265
- } catch {
266
- return false;
267
- }
257
+ function matchesOwnedTree(path, owner) {
258
+ return treeMatches(path, owner.previousVersion, owner.previousTreeIdentity);
268
259
  }
269
- async function matchesInstalledTree(path, owner) {
270
- try {
271
- const info = await lstat(path);
272
- return info.isDirectory() && !info.isSymbolicLink() && await readUpdateTreeVersion(path) === owner.newVersion && sameUpdateTreeIdentity(await readUpdateTreeIdentity(path), owner.newTreeIdentity);
273
- } catch {
274
- return false;
275
- }
260
+ function matchesInstalledTree(path, owner) {
261
+ return treeMatches(path, owner.newVersion, owner.newTreeIdentity);
276
262
  }
277
263
  function isMatchingHealthTemporary(name) {
278
264
  return name.startsWith(".healthy-") && name.endsWith(".tmp") && isUuid(name.slice(9, -4));
@@ -306,4 +292,4 @@ function generationFromClaimName(name, target) {
306
292
  const generation = name.slice(prefix.length, -11);
307
293
  return isUuid(generation) ? generation : void 0;
308
294
  }
309
- export { PUBLISHER_TEMP_UUID, VERSION, cleanupMarkerMatches, ensureClaim, ensureCleanupMarker, generationFromClaimName, hasExactOwnKeys, healthReceiptFor, healthReceiptMatches, isMatchingHealthTemporary, matchesInstalledTree, matchesOldTree, matchesOwnedTree, matchesPartiallyPrunedContainer, ownerFor, ownerMatches, parseHealthReceipt, parseOwner, pathInfo, readCleanupMarker, readHealthReceipt, readOwner, samePathTreeIdentity, updateRetirementPaths, validRetirementContainer };
295
+ export { cleanupMarkerMatches, ensureClaim, ensureCleanupMarker, generationFromClaimName, healthReceiptFor, healthReceiptMatches, isMatchingHealthTemporary, matchesInstalledTree, matchesOldTree, matchesOwnedTree, matchesPartiallyPrunedContainer, ownerFor, ownerMatches, parseHealthReceipt, parseOwner, pathInfo, readCleanupMarker, readHealthReceipt, readOwner, samePathTreeIdentity, updateRetirementPaths, validRetirementContainer };
@@ -36,6 +36,10 @@ export declare class UpdateRetentionPublicationError extends Error {
36
36
  readonly temporaryPath: string;
37
37
  constructor(temporaryPath: string, cause: unknown);
38
38
  }
39
+ /** Lowercase-only, so one generation cannot gain two spellings in marker names. */
40
+ export declare const LOWERCASE_UUID: RegExp;
41
+ /** A persisted device/inode pair with exactly those two decimal string fields. */
42
+ export declare function isTreeIdentity(value: unknown): value is UpdateTreeIdentity;
39
43
  /** Return the stable, generation-specific intent path beside the install. */
40
44
  export declare function updateRetentionIntentPath(target: string, generation: string): string;
41
45
  /**
@@ -1,4 +1,4 @@
1
- import { errorCode } from "../../app/value-guards.js";
1
+ import { errorCode, hasExactOwnKeys, isRecord } from "../../app/value-guards.js";
2
2
  import { isCanonicalPath } from "../../native/canonical-path.js";
3
3
  import { link, lstat, open, unlink, writeFile } from "node:fs/promises";
4
4
  import { basename, dirname, join } from "node:path";
@@ -18,23 +18,18 @@ var UpdateRetentionPublicationError = class extends Error {
18
18
  this.name = "UpdateRetentionPublicationError";
19
19
  }
20
20
  };
21
- var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
21
+ /** Lowercase-only, so one generation cannot gain two spellings in marker names. */
22
+ var LOWERCASE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
22
23
  var IDENTITY_COMPONENT = /^[1-9]\d{0,19}$/;
23
24
  var MAX_MARKER_BYTES = 2048;
24
25
  function assertCanonicalTarget(target) {
25
26
  if (!isCanonicalPath(target)) throw new Error("Invalid update retention target");
26
27
  }
27
28
  function assertGeneration(generation) {
28
- if (typeof generation !== "string" || !UUID.test(generation)) throw new Error("Invalid update retention generation");
29
+ if (typeof generation !== "string" || !LOWERCASE_UUID.test(generation)) throw new Error("Invalid update retention generation");
29
30
  }
30
- function isRecord(value) {
31
- return typeof value === "object" && value !== null && !Array.isArray(value);
32
- }
33
- function hasExactOwnKeys(value, expected) {
34
- const actual = Reflect.ownKeys(value);
35
- return actual.length === expected.length && actual.every((key) => typeof key === "string" && expected.includes(key));
36
- }
37
- function isIdentity(value) {
31
+ /** A persisted device/inode pair with exactly those two decimal string fields. */
32
+ function isTreeIdentity(value) {
38
33
  if (!isRecord(value)) return false;
39
34
  return hasExactOwnKeys(value, ["device", "inode"]) && typeof value.device === "string" && IDENTITY_COMPONENT.test(value.device) && typeof value.inode === "string" && IDENTITY_COMPONENT.test(value.inode);
40
35
  }
@@ -48,7 +43,7 @@ function parseUpdateRetentionIntent(value, target, generation) {
48
43
  "previousTreeIdentity",
49
44
  "installedGeneration",
50
45
  "installedTreeIdentity"
51
- ]) || value.schema !== 1 || value.phase !== "prune-previous-tree" || value.target !== target || value.generation !== generation || typeof value.installedGeneration !== "string" || !UUID.test(value.installedGeneration) || !isIdentity(value.previousTreeIdentity) || !isIdentity(value.installedTreeIdentity)) throw new Error("Invalid update retention intent");
46
+ ]) || value.schema !== 1 || value.phase !== "prune-previous-tree" || value.target !== target || value.generation !== generation || typeof value.installedGeneration !== "string" || !LOWERCASE_UUID.test(value.installedGeneration) || !isTreeIdentity(value.previousTreeIdentity) || !isTreeIdentity(value.installedTreeIdentity)) throw new Error("Invalid update retention intent");
52
47
  return Object.freeze({
53
48
  schema: 1,
54
49
  phase: "prune-previous-tree",
@@ -129,7 +124,7 @@ async function readUpdateRetentionIntentFile(path, target, generation) {
129
124
  const temporaryPrefix = `.${basename(marker)}.`;
130
125
  const name = basename(path);
131
126
  const temporaryId = name.startsWith(temporaryPrefix) && name.endsWith(".tmp") ? name.slice(temporaryPrefix.length, -4) : "";
132
- const isCanonicalTemporary = dirname(path) === dirname(marker) && join(dirname(marker), name) === path && UUID.test(temporaryId);
127
+ const isCanonicalTemporary = dirname(path) === dirname(marker) && join(dirname(marker), name) === path && LOWERCASE_UUID.test(temporaryId);
133
128
  if (path !== marker && !isCanonicalTemporary) throw new Error("Invalid update retention intent path");
134
129
  let pathInfo;
135
130
  try {
@@ -164,4 +159,4 @@ async function readUpdateRetentionIntentFile(path, target, generation) {
164
159
  await file.close();
165
160
  }
166
161
  }
167
- export { UpdateRetentionPublicationError, publishUpdateRetentionIntent, readUpdateRetentionIntent, readUpdateRetentionIntentFile, sameRetentionIntent, updateRetentionIntentPath };
162
+ export { LOWERCASE_UUID, UpdateRetentionPublicationError, isTreeIdentity, publishUpdateRetentionIntent, readUpdateRetentionIntent, readUpdateRetentionIntentFile, sameRetentionIntent, updateRetentionIntentPath };
@@ -1,5 +1,17 @@
1
1
  import { type UpdateStageState } from '../update-state-store';
2
2
  import { type UpdateHealthAcknowledgement } from './retirement-records';
3
+ /**
4
+ * Record health for the generations behind an acknowledged installed generation. Each of
5
+ * them installed a tree that went on to run and apply the next update, so it was healthy;
6
+ * apps that acknowledged health only for the latest generation, or not at all before
7
+ * automatic acknowledgement, otherwise leave their older trees unprunable forever. Writes
8
+ * nothing unless the installed generation is acknowledged and its lineage validates.
9
+ * Returns how many receipts it wrote.
10
+ */
11
+ export declare function acknowledgeRetiredUpdateLineage(options: {
12
+ target: string;
13
+ currentVersion: string;
14
+ }): Promise<number>;
3
15
  /** Explicitly acknowledge an exact installed generation after app-owned readiness checks. */
4
16
  export declare function acknowledgeRetiredUpdateHealthy(options: {
5
17
  target: string;