edsp: document unique package identifiers

Document that package identifiers must be unique (apt only uses the last
action for a given identifier) and that install requests do also imply
upgrades and downgrades (and thus removal of the old version). This is
to prevent that solvers express an upgrade or downgrade instruction as
two stanzas: a removal of the old version and an installation of the new
version. Instead, a single install stanza is sufficient to express
upgrade or downgrade requests.

diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt
index e2bd95866f303abea02de859fbdff9202a7d5672..d914db30930008b1a98c92711e674c974176f687 100644 (file)
--- a/doc/external-dependency-solver-protocol.txt
+++ b/doc/external-dependency-solver-protocol.txt
@@ -263,11 +263,11 @@ the user.
 
 #### Solution
 
-A solution is a list of Deb 822 stanzas. Each of them could be an
-install stanza (telling APT to install a specific package), a remove
-stanza (telling APT to remove one), or an autoremove stanza (telling APT
-about the *future* possibility of removing a package using the
-Autoremove action).
+A solution is a list of Deb 822 stanzas. Each of them could be an install
+stanza (telling APT to install a specific new package or to upgrade or
+downgrade a package to a specific version), a remove stanza (telling APT to
+remove one), or an autoremove stanza (telling APT about the *future*
+possibility of removing a package using the Autoremove action).
 
 An **install stanza** starts with an Install field and supports the
 following fields:
@@ -289,6 +289,11 @@ this protocol makes no assumption on the fact that a subsequent
 invocation of an Autoremove action will actually remove the very same
 packages indicated by Autoremove stanzas in the former solution.
 
+The package identifiers of install, remove and autoremove stanzas from a single
+solution are unique. That is, a package identifier does not occur more than
+once in the solution. Every package identifier is only associated with a single
+action (either install, remove or autoremove).
+
 In terms of expressivity, install and remove stanzas can carry one
 single field each, as APT-IDs are enough to pinpoint packages to be
 installed/removed. Nonetheless, for protocol readability, it is