Meta: Allow registering meta keys that skip query cache invalidation

Add `invalidates_query_cache` parameter to `register_meta()`. Meta keys
registered with this set to `false` will not bump the `last_changed`
timestamp for the parent object's cache group when added, updated, or
deleted. This prevents high-frequency meta writes from invalidating
query caches site-wide.

Meta keys registered as non-query-cacheable are also blocked from use
in `WP_Meta_Query` clauses, since skipping cache invalidation would
lead to stale query results.

Registers the real-time collaboration meta keys (`wp_sync_awareness`
and `wp_sync_update`) with this flag to resolve the cache invalidation
issue described in https://core.trac.wordpress.org/ticket/64696.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: ellatrix

src/wp-includes/class-wp-meta-query.php

@@ -95,6 +95,14 @@ class WP_Meta_Query {
 	 */
 	protected $has_or_relation = false;
 
+	/**
+	 * The type of object metadata is for (e.g. 'post', 'user', 'term').
+	 *
+	 * @since 7.0.0
+	 * @var string
+	 */
+	protected $object_type = '';
+
 	/**
 	 * Constructor.
 	 *
@@ -364,6 +372,7 @@ public function get_sql( $type, $primary_table, $primary_id_column, $context = n
 
 		$this->meta_table     = $meta_table;
 		$this->meta_id_column = sanitize_key( $type . '_id' );
+		$this->object_type    = $type;
 
 		$this->primary_table     = $primary_table;
 		$this->primary_id_column = $primary_id_column;
@@ -533,6 +542,28 @@ protected function get_sql_for_query( &$query, $depth = 0 ) {
 	public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) {
 		global $wpdb;
 
+		// Refuse to query by a meta key registered as non-query-cacheable.
+		if ( $this->object_type
+			&& isset( $clause['key'] )
+			&& is_string( $clause['key'] )
+			&& ! wp_meta_key_invalidates_query_cache( $this->object_type, $clause['key'] )
+		) {
+			_doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					/* translators: %s: The meta key. */
+					__( 'The meta key "%s" is registered with invalidates_query_cache set to false and cannot be used in meta queries.' ),
+					$clause['key']
+				),
+				'7.0.0'
+			);
+
+			return array(
+				'join'  => array(),
+				'where' => array(),
+			);
+		}
+
 		$sql_chunks = array(
 			'where' => array(),
 			'join'  => array(),

src/wp-includes/default-filters.php

@@ -122,9 +122,9 @@
 }
 
 // Post meta.
-add_action( 'added_post_meta', 'wp_cache_set_posts_last_changed' );
-add_action( 'updated_post_meta', 'wp_cache_set_posts_last_changed' );
-add_action( 'deleted_post_meta', 'wp_cache_set_posts_last_changed' );
+add_action( 'added_post_meta', 'wp_cache_set_posts_last_changed', 10, 3 );
+add_action( 'updated_post_meta', 'wp_cache_set_posts_last_changed', 10, 3 );
+add_action( 'deleted_post_meta', 'wp_cache_set_posts_last_changed', 10, 3 );
 
 // User meta.
 add_action( 'added_user_meta', 'wp_cache_set_users_last_changed' );

src/wp-includes/meta.php

@@ -1440,16 +1440,17 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
 	}
 
 	$defaults = array(
-		'object_subtype'    => '',
-		'type'              => 'string',
-		'label'             => '',
-		'description'       => '',
-		'default'           => '',
-		'single'            => false,
-		'sanitize_callback' => null,
-		'auth_callback'     => null,
-		'show_in_rest'      => false,
-		'revisions_enabled' => false,
+		'object_subtype'           => '',
+		'type'                     => 'string',
+		'label'                    => '',
+		'description'              => '',
+		'default'                  => '',
+		'single'                   => false,
+		'sanitize_callback'        => null,
+		'auth_callback'            => null,
+		'show_in_rest'             => false,
+		'revisions_enabled'        => false,
+		'invalidates_query_cache'  => true,
 	);
 
 	// There used to be individual args for sanitize and auth callbacks.
@@ -1644,6 +1645,43 @@ function registered_meta_key_exists( $object_type, $meta_key, $object_subtype =
 	return isset( $meta_keys[ $meta_key ] );
 }
 
+/**
+ * Checks whether a meta key invalidates query caches when updated.
+ *
+ * Meta keys registered with `'invalidates_query_cache' => false` will not
+ * cause query cache invalidation when added, updated, or deleted. This is
+ * useful for high-frequency meta that is never used in query filters, such
+ * as real-time collaboration sync data.
+ *
+ * Unregistered meta keys are assumed to invalidate query caches.
+ *
+ * @since 7.0.0
+ *
+ * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
+ *                               or any other object type with an associated meta table.
+ * @param string $meta_key       Metadata key.
+ * @param string $object_subtype Optional. The subtype of the object type. Default empty string.
+ * @return bool True if the meta key invalidates query caches, false otherwise.
+ */
+function wp_meta_key_invalidates_query_cache( $object_type, $meta_key, $object_subtype = '' ) {
+	$meta_keys = get_registered_meta_keys( $object_type, $object_subtype );
+
+	if ( isset( $meta_keys[ $meta_key ] ) ) {
+		return $meta_keys[ $meta_key ]['invalidates_query_cache'];
+	}
+
+	// Also check keys registered without a subtype.
+	if ( '' !== $object_subtype ) {
+		$meta_keys = get_registered_meta_keys( $object_type );
+		if ( isset( $meta_keys[ $meta_key ] ) ) {
+			return $meta_keys[ $meta_key ]['invalidates_query_cache'];
+		}
+	}
+
+	// Unregistered keys default to invalidating caches.
+	return true;
+}
+
 /**
  * Unregisters a meta key from the list of registered keys.
  *

src/wp-includes/post.php

@@ -690,6 +690,22 @@ function create_initial_post_types() {
 				'supports'           => array( 'custom-fields' ),
 			)
 		);
+
+		register_post_meta(
+			'wp_sync_storage',
+			'wp_sync_awareness',
+			array(
+				'invalidates_query_cache' => false,
+			)
+		);
+
+		register_post_meta(
+			'wp_sync_storage',
+			'wp_sync_update',
+			array(
+				'invalidates_query_cache' => false,
+			)
+		);
 	}
 
 	register_post_status(
@@ -8439,9 +8455,23 @@ function wp_add_trashed_suffix_to_post_name_for_post( $post ) {
 /**
  * Sets the last changed time for the 'posts' cache group.
  *
+ * When called from a post meta action (`added_post_meta`, `updated_post_meta`,
+ * or `deleted_post_meta`), the meta key is checked against the registered meta
+ * registry. If the meta key was registered with `'invalidates_query_cache' => false`,
+ * the cache is not invalidated. This allows high-frequency meta writes (e.g.
+ * real-time collaboration data) to avoid invalidating query caches site-wide.
+ *
  * @since 5.0.0
+ * @since 7.0.0 Added the `$meta_id`, `$object_id`, and `$meta_key` parameters.
+ *
+ * @param int    $meta_id   Optional. Meta ID. Passed by meta action hooks.
+ * @param int    $object_id Optional. Object ID. Passed by meta action hooks.
+ * @param string $meta_key  Optional. Meta key. Passed by meta action hooks.
  */
-function wp_cache_set_posts_last_changed() {
+function wp_cache_set_posts_last_changed( $meta_id = 0, $object_id = 0, $meta_key = '' ) {
+	if ( $meta_key && ! wp_meta_key_invalidates_query_cache( 'post', $meta_key ) ) {
+		return;
+	}
 	wp_cache_set_last_changed( 'posts' );
 }