Explain futureproofing store files

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md
index 6d09db0c..2b53dca8 100644
--- a/doc/src/02000-store.md
+++ b/doc/src/02000-store.md
@@ -126,6 +126,26 @@ sub-folders like this:
 /module/some/sub/folder/example~0.1
 ```
 
+A given file MUST only exist once with the same path.
+For example, it is invalid if these files exist at the same time:
+
+* /foo/bar~0.2
+* /foo/bar~1.3
+
+To future-proof the System it is thus necessary to create a disambiguation at
+the store level. Thus if a library wants to retrieve a file from the Store
+it MUST at least accept files from it's current advertised version. It MAY
+accept older files and it MAY transform them and resubmit them in the newer
+version.
+
+For this there will be an enum returned for each given Entry. It will have these
+members:
+
+- `Compatible`, for version matches
+- `PossiblyIncompatible`, if the current version is at least a major number
+  further
+- `Incompatible`, if the file is a at least a major number further
+
 ## Store path links {#sec:thestore:links}
 
 Linking entries MUST BE version independent.