diff --git a/external/extension.mdx b/external/extension.mdx
index 9a8dae94..b09ecf52 100644
--- a/external/extension.mdx
+++ b/external/extension.mdx
@@ -278,6 +278,14 @@ version. The first time the extension is evaluated, it can fetch this mapping
 from the network, but on later evaluations it can use the mapping from `facts`
 to avoid the network requests.
 
+If you need to make a backwards-incompatible change to the schema of the values
+your extension stores in `facts`, set the
+[`facts_version`](/rules/lib/globals/bzl#module_extension.facts_version)
+parameter on `module_extension` to a higher integer than its previous value.
+Bazel persists `facts_version` in the lockfile alongside the facts and discards
+any persisted facts when the recorded version differs from the current one,
+making sure your extension only ever observes facts produced by the same schema.
+
 ### Specify dependence on operating system and architecture
 
 If your extension relies on the operating system or its architecture type,
diff --git a/rules/lib/globals/bzl.mdx b/rules/lib/globals/bzl.mdx
index 0609f741..fca55ead 100644
--- a/rules/lib/globals/bzl.mdx
+++ b/rules/lib/globals/bzl.mdx
@@ -202,7 +202,7 @@ Materializer targets are used to dynamically select dependencies at analysis tim
 ## module_extension
 
 ```
-unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)
+unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False, facts_version=0)
 ```
 
 Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with `use_extension`.
@@ -217,6 +217,7 @@ Creates a new module extension. Store it in a global value, so that it can be ex
 | `environ` | [sequence](../core/list) of [string](../core/string)s; default is `[]`  **Deprecated**. This parameter has been deprecated. Migrate to `module_ctx.getenv` instead.  Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated.  See also `--experimental_strict_repo_env`. |
 | `os_dependent` | [bool](../core/bool); default is `False`  Indicates whether this extension is OS-dependent or not |
 | `arch_dependent` | [bool](../core/bool); default is `False`  Indicates whether this extension is architecture-dependent or not |
+| `facts_version` | [int](../core/int); default is `0`  The schema version of the `facts` dict returned by this extension's implementation function via `extension_metadata`. The version is persisted in the lockfile alongside the facts and compared against the current value before the extension runs: if they differ, the persisted facts are discarded and the extension is invoked with an empty `module_ctx.facts`. Increment this value whenever the extension changes the schema of the facts in a backwards-incompatible way so that older facts are not interpreted with the new schema. |
 
 ## provider
 
diff --git a/upstream b/upstream
index fdba6e6b..87f096a2 160000
--- a/upstream
+++ b/upstream
@@ -1 +1 @@
-Subproject commit fdba6e6bda1ff9423b111eb099f4f9f6e0d34115
+Subproject commit 87f096a2c6b21b1214955caf127b4975c5a58a88