Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

build(cua-driver): add Omarchy profile measurement and rebuild guidance (#4383)

Francesco Bonacci477d2d87cd11
diff --git a/libs/cua-driver/hyprland-plugin/packaging/release/profile-contract.md b/libs/cua-driver/hyprland-plugin/packaging/release/profile-contract.md
index 59216b21fb..e3847f51c7 100644
--- a/libs/cua-driver/hyprland-plugin/packaging/release/profile-contract.md
+++ b/libs/cua-driver/hyprland-plugin/packaging/release/profile-contract.md
@@ -95,3 +95,34 @@ The downstream implementation remains
[omacom/omarchy-pkgs#346](https://github.com/omacom/omarchy-pkgs/pull/346).
This document records the selected contract, not completed package or native
validation.
+
+## Measuring a new channel candidate
+
+From the release tooling directory, `profile_measure.py measure` measures an
+installed Linux x86_64 environment. Supply the independently reviewed source
+revision, Driver version, archive and manifest digests; the helper does not
+select a source or trust digests from an unreviewed archive. Its output is a
+candidate for review, never a compatibility or certification declaration.
+
+```sh
+python3 profile_measure.py measure --profile-id omarchy-edge-YYYYMMDD \
+ --kit-version KIT_VERSION --package-release PACKAGE_RELEASE \
+ --revision SOURCE_REVISION --driver-version DRIVER_VERSION \
+ --archive SOURCE_ARCHIVE --archive-sha256 REVIEWED_ARCHIVE_SHA256 \
+ --manifest-sha256 REVIEWED_MANIFEST_SHA256 --cxx /usr/bin/g++ \
+ --output candidate-profile.json
+python3 profile_measure.py reuse --reviewed reviewed-profile.json \
+ --candidate candidate-profile.json
+```
+
+The comparison reports `profile-unchanged`, `relabel-rebuild`, or `rebuild`.
+Run `measure` on the target host immediately before comparing it; `reuse` is
+only an offline data comparison, not a host check. It exits 3 for a required
+rebuild, 2 for invalid CLI usage, and 1 for validation errors.
+Even `profile-unchanged` compares only profile data: separately verify unchanged
+tooling, kit, module and package bytes and the applicable qualification evidence.
+The JSON always reports `qualification_verified: false`. A changed package
+release or profile label requires rebuilding and affected lifecycle evidence;
+changed source, compiler, headers, compositor or runtime inputs require a new
+reviewed profile and affected native qualification. A matching Hyprland version
+string alone is insufficient after an Arch package rebuild.
diff --git a/libs/cua-driver/hyprland-plugin/packaging/release/profile_measure.py b/libs/cua-driver/hyprland-plugin/packaging/release/profile_measure.py
new file mode 100644
index 0000000000..962482daad
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/packaging/release/profile_measure.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Measure a native Omarchy host into a candidate profile, and classify rebuild reuse.
+
+The output is reviewed data for profile_bundle.py, never certification. The
+reviewer supplies the source identity and digests as trust roots; this tool
+only measures the native environment and refuses a source that does not match.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tarfile
+
+import profile_verify as verify
+
+HYPRLAND = Path("/usr/bin/Hyprland")
+SOURCE_FIELDS = ("revision", "driver_version", "archive_sha256", "manifest_sha256")
+# Sections whose change alters package bytes or ABI and needs a new build and requalification.
+SECTIONS = ("source", "architecture", "hyprland", "compiler", "runtime")
+LABELS = ("schema", "profile_id", "kit_version", "package_release")
+
+
+def compositor_libraries():
+ """Resolved shared-library paths of the installed compositor, by soname."""
+ libraries = {}
+ for line in verify.run("ldd", str(HYPRLAND)).splitlines():
+ match = re.fullmatch(r"\s*(\S+) => (/\S+) \(0x[0-9a-fA-F]+\)\s*", line)
+ if match:
+ libraries[match[1]] = Path(match[2]).resolve(strict=True)
+ return libraries
+
+
+def owner_versions(paths):
+ owners = {verify.run("pacman", "-Qoq", str(path)) for path in paths}
+ return {name: verify.run("pacman", "-Q", name).split(" ", 1)[1] for name in sorted(owners)}
+
+
+def measure(profile_id, kit_version, package_release, source, archive, cxx):
+ """Return a candidate schema-2 profile measured from this host."""
+ verify.require(set(source) == set(SOURCE_FIELDS), "source must name " + ", ".join(SOURCE_FIELDS))
+ verify.require(not any(key.startswith("LD_") for key in os.environ),
+ "clear dynamic-loader LD_* overrides before measuring")
+ verify.require(verify.platform.system() == "Linux" and verify.platform.machine() == "x86_64", "requires Linux x86_64")
+ verify.require(cxx.is_absolute() and cxx.is_file(), "C++ compiler must be an existing absolute path")
+ libraries = compositor_libraries()
+ verify.require("libstdc++.so.6" in libraries, "compositor does not use shared libstdc++")
+ runtime = libraries["libstdc++.so.6"]
+ compiler_runtime = Path(verify.run(str(cxx), "--print-file-name=libstdc++.so.6")).resolve(strict=True)
+ verify.require(compiler_runtime == runtime, "compiler and compositor resolve different shared libstdc++ files")
+ macros = verify.run(str(cxx), "-dM", "-E", "-x", "c++", "-", input="")
+ version = re.search(r'^#define __VERSION__ "([^"]+)"$', macros, re.MULTILINE)
+ verify.require(version and not re.search(r"^#define __clang__\b", macros, re.MULTILINE), "compiler must be GCC with a version/date")
+ profile = {
+ "schema": 2, "profile_id": profile_id, "kit_version": kit_version, "package_release": package_release,
+ "source": dict(source), "architecture": "x86_64",
+ "hyprland": {
+ "package_version": verify.run("pacman", "-Q", "hyprland").split(" ", 1)[1],
+ "header_version": verify.run(str(verify.PKGCONF), "--modversion", "hyprland", extra_env=verify.PKGCONF_ENV),
+ "headers_sha256": verify.header_inventory_sha256(), "sha256": verify.digest(HYPRLAND)},
+ "compiler": {"version": version[1], "comment": "GCC: (GNU) " + version[1], "sha256": verify.digest(cxx)},
+ # Packages are the owners of every library the compositor resolves; the reviewer confirms the set.
+ "runtime": {"basename": runtime.name, "sha256": verify.digest(runtime),
+ "packages": owner_versions(set(libraries.values()))},
+ }
+ verify.validate_profile(profile)
+ verify.verify_archive(archive, profile)
+ # Self-consistency only: proves the profile matches this host, not that it is qualified.
+ verify.verify_native(cxx, profile)
+ return profile
+
+
+def reuse_decision(reviewed, candidate):
+ """Compare profile inputs; this does not compare package or evidence bytes.
+
+ "profile-unchanged": identical profile data; independently verify package bytes and evidence.
+ "relabel-rebuild": only schema, profile_id, kit_version or package_release differ; the
+ package bytes change, so the affected evidence is repeated.
+ "rebuild": source, architecture, compositor, headers, compiler or ABI runtime differ.
+ """
+ verify.validate_profile(reviewed)
+ verify.validate_profile(candidate)
+ reasons = [f"{name} differs" for name in SECTIONS if reviewed[name] != candidate[name]]
+ if reasons:
+ return "rebuild", reasons
+ reasons = [f"{name} differs" for name in LABELS if reviewed[name] != candidate[name]]
+ return ("relabel-rebuild", reasons) if reasons else ("profile-unchanged", [])
+
+
+def load(path):
+ return verify.validate_profile(verify.read_json(path.read_bytes()))
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ sub = parser.add_subparsers(dest="command", required=True)
+ m = sub.add_parser("measure", help="write a candidate profile from this host")
+ m.add_argument("--profile-id", required=True)
+ m.add_argument("--kit-version", required=True)
+ m.add_argument("--package-release", required=True, type=int)
+ m.add_argument("--revision", required=True, help="reviewed full source commit SHA")
+ m.add_argument("--driver-version", required=True)
+ m.add_argument("--archive", required=True, type=Path)
+ m.add_argument("--archive-sha256", required=True, help="independently reviewed archive digest")
+ m.add_argument("--manifest-sha256", required=True, help="independently reviewed manifest digest")
+ m.add_argument("--cxx", required=True, type=Path)
+ m.add_argument("--output", required=True, type=Path, help="new profile file")
+ r = sub.add_parser("reuse", help="classify whether reviewed evidence survives a candidate profile")
+ r.add_argument("--reviewed", required=True, type=Path)
+ r.add_argument("--candidate", required=True, type=Path)
+ args = parser.parse_args()
+ try:
+ if args.command == "measure":
+ source = {"revision": args.revision, "driver_version": args.driver_version,
+ "archive_sha256": args.archive_sha256, "manifest_sha256": args.manifest_sha256}
+ profile = measure(args.profile_id, args.kit_version, args.package_release, source, args.archive, args.cxx)
+ with args.output.open("xb") as handle:
+ handle.write(verify.json_bytes(profile))
+ print(f"Wrote candidate {args.output}; review it. It is not native certification.")
+ else:
+ verdict, reasons = reuse_decision(load(args.reviewed), load(args.candidate))
+ print(json.dumps({"verdict": verdict, "reasons": reasons, "qualification_verified": False}))
+ sys.exit(0 if verdict == "profile-unchanged" else 3)
+ except (ValueError, KeyError, TypeError, OSError, tarfile.TarError, subprocess.CalledProcessError) as error:
+ parser.exit(1, f"error: {error}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/cua-driver/hyprland-plugin/packaging/release/test_profile_measure.py b/libs/cua-driver/hyprland-plugin/packaging/release/test_profile_measure.py
new file mode 100644
index 0000000000..ead9ea3007
--- /dev/null
+++ b/libs/cua-driver/hyprland-plugin/packaging/release/test_profile_measure.py
@@ -0,0 +1,104 @@
+"""Profile measurement and rebuild-reuse contracts, with synthetic native command responses."""
+
+import copy
+import io
+import json
+import os
+from pathlib import Path
+import tempfile
+import unittest
+from unittest import mock
+
+import profile_measure as measure
+import profile_verify as verify
+import test_profile_release as fixtures
+
+GCC = "16.2.1 20260810"
+
+
+class MeasureTest(fixtures.ProfileTest):
+ schema = 2
+ source_revision = "c" * 40
+ driver_version = "0.31.0"
+
+ def commands(self, runtime_path, compiler_runtime=None, owners=None):
+ owners = owners or {"/usr/lib/libstdc++.so.6.0.99": "gcc-libs", "/usr/lib/libwayland-server.so.0": "wayland"}
+ versions = {"hyprland": "hyprland 0.56.2-2", "gcc-libs": "gcc-libs 16.2.1-1", "wayland": "wayland 1.26.0-1"}
+
+ def run(*command, input=None, extra_env=None):
+ if command[0] == "ldd":
+ return ("\tlibstdc++.so.6 => /usr/lib/libstdc++.so.6.0.99 (0x1)\n"
+ "\tlibwayland-server.so.0 => /usr/lib/libwayland-server.so.0 (0x2)")
+ if command[:2] == ("pacman", "-Qoq"):
+ return owners[command[2]]
+ if command[:2] == ("pacman", "-Q"):
+ return versions[command[2]]
+ if "--print-file-name=libstdc++.so.6" in command:
+ return compiler_runtime or "/usr/lib/libstdc++.so.6.0.99"
+ if "-dM" in command:
+ return f'#define __VERSION__ "{GCC}"'
+ if "--modversion" in command:
+ return "0.56.2"
+ raise AssertionError(command)
+ return run
+
+ def run_measure(self, **kwargs):
+ cxx = self.root / "g++"
+ cxx.write_bytes(b"compiler")
+ paths = {"/usr/lib/libstdc++.so.6.0.99": Path("/usr/lib/libstdc++.so.6.0.99"),
+ "/usr/lib/libwayland-server.so.0": Path("/usr/lib/libwayland-server.so.0")}
+ digests = {"/usr/bin/Hyprland": "a" * 64, str(cxx): "b" * 64, "/usr/lib/libstdc++.so.6.0.99": "c" * 64}
+ with mock.patch.object(verify, "run", side_effect=self.commands(None, **kwargs)), \
+ mock.patch.object(verify, "digest", side_effect=lambda path: digests.get(str(path)) or verify.sha256(path.read_bytes())), \
+ mock.patch.object(verify, "header_inventory_sha256", return_value="d" * 64), \
+ mock.patch.object(verify, "verify_native") as native, \
+ mock.patch.object(verify.platform, "system", return_value="Linux"), \
+ mock.patch.object(verify.platform, "machine", return_value="x86_64"), \
+ mock.patch.object(Path, "resolve", lambda self, strict=False: self):
+ profile = measure.measure("synthetic-native", "1.0.0", 2, dict(self.profile["source"]), self.archive, cxx)
+ native.assert_called_once()
+ return profile
+
+ def test_measured_profile_matches_reviewed_shape_and_source(self):
+ profile = self.run_measure()
+ self.assertEqual(profile, self.profile | {"runtime": {**self.profile["runtime"],
+ "packages": {"gcc-libs": "16.2.1-1", "wayland": "1.26.0-1"}}})
+
+ def test_source_digest_substitution_refused(self):
+ self.profile["source"]["archive_sha256"] = "0" * 64
+ with self.assertRaisesRegex(ValueError, "source archive checksum mismatch"):
+ self.run_measure()
+
+ def test_compiler_and_compositor_runtime_must_match(self):
+ with self.assertRaisesRegex(ValueError, "different shared libstdc"):
+ self.run_measure(compiler_runtime="/usr/lib/other/libstdc++.so.6.0.99")
+
+ def test_reuse_rules(self):
+ reviewed = verify.validate_profile(copy.deepcopy(self.profile))
+ self.assertEqual(measure.reuse_decision(reviewed, copy.deepcopy(reviewed)), ("profile-unchanged", []))
+ relabeled = copy.deepcopy(reviewed)
+ relabeled["package_release"] = 3
+ self.assertEqual(measure.reuse_decision(reviewed, relabeled), ("relabel-rebuild", ["package_release differs"]))
+ for section, change in (("source", ("archive_sha256", "e" * 64)), ("hyprland", ("sha256", "e" * 64)),
+ ("compiler", ("sha256", "e" * 64)), ("runtime", ("sha256", "e" * 64))):
+ changed = copy.deepcopy(reviewed)
+ changed[section][change[0]] = change[1]
+ self.assertEqual(measure.reuse_decision(reviewed, changed), ("rebuild", [f"{section} differs"]))
+ dependency = copy.deepcopy(reviewed)
+ dependency["runtime"]["packages"]["gcc-libs"] = "16.2.1-2"
+ self.assertEqual(measure.reuse_decision(reviewed, dependency)[0], "rebuild")
+
+ def test_reuse_refuses_invalid_profile(self):
+ invalid = copy.deepcopy(self.profile)
+ invalid["compiler"]["sha256"] = "short"
+ with self.assertRaisesRegex(ValueError, "lowercase SHA-256"):
+ measure.reuse_decision(self.profile, invalid)
+
+ def test_measure_refuses_loader_override(self):
+ with mock.patch.dict(os.environ, {"LD_LIBRARY_PATH": "/synthetic"}):
+ with self.assertRaisesRegex(ValueError, "dynamic-loader"):
+ self.run_measure()
+
+
+if __name__ == "__main__":
+ unittest.main()