<?php
/**
 * Routing predicate — centralises Zone ownership and activation checks.
 *
 * Two recurring predicates previously scattered across callers:
 *
 * 1. entity_bridge_owns(): was TMDO_Sync_Bridge::is_owned_by_entity_bridge() —
 *    answers "does the Hook Bus own this meta_key (Zone Bridge must skip it)?".
 *
 * 2. should_write_to_zone() / should_read_from_zone() / should_query_from_zone():
 *    were inline TMDO_Zone_Router::module_name() + TMDO_Feature_Flags::is_*()
 *    pairs repeated in Sync_Bridge, Query_Router, and REST API.
 *
 * @package TMDO
 * @since 0.2.0
 */

declare(strict_types=1);

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Centralised routing predicate for Zone write/read/query activation checks.
 */
class TMDO_Routing_Predicate {

	/**
	 * Request-level cache for entity_bridge_owns().
	 *
	 * @var array<string, bool>
	 */
	private static array $entity_bridge_cache = array();

	/**
	 * Returns true when the Entity Bridge (Hook Bus) owns writes for $meta_key on
	 * the 'post' entity type — Zone Sync_Bridge must not also write to a Zone table.
	 *
	 * Replaces the former TMDO_Sync_Bridge::is_owned_by_entity_bridge().
	 *
	 * @param string $meta_key Meta key being written.
	 * @return bool
	 */
	public static function entity_bridge_owns( string $meta_key ): bool {
		if ( isset( self::$entity_bridge_cache[ $meta_key ] ) ) {
			return self::$entity_bridge_cache[ $meta_key ];
		}

		$result = false;
		if ( class_exists( 'TMDO_Mode_Manager' )
			&& class_exists( 'TMDO_Entity_Registry' )
			&& TMDO_Mode_Manager::writes_to_flat( 'post' )
			&& null !== TMDO_Entity_Registry::get_field( 'post', $meta_key ) ) {
			$result = true;
		}

		self::$entity_bridge_cache[ $meta_key ] = $result;
		return $result;
	}

	/**
	 * Returns true when Zone dual-write is active for the given post_type + zone.
	 *
	 * Replaces the repeated inline pattern:
	 *   $module = TMDO_Zone_Router::module_name( $zone, $post_type );
	 *   TMDO_Feature_Flags::is_write_active( $module );
	 *
	 * @param string $post_type Post type slug.
	 * @param string $zone      Zone identifier: 'hot', 'cold', 'warm', 'archive'.
	 * @return bool
	 */
	public static function should_write_to_zone( string $post_type, string $zone ): bool {
		return TMDO_Feature_Flags::is_write_active(
			TMDO_Zone_Router::module_name( $zone, $post_type )
		);
	}

	/**
	 * Returns true when Zone read-from-custom is active for the given post_type + zone.
	 *
	 * @param string $post_type Post type slug.
	 * @param string $zone      Zone identifier.
	 * @return bool
	 */
	public static function should_read_from_zone( string $post_type, string $zone ): bool {
		return TMDO_Feature_Flags::is_read_custom(
			TMDO_Zone_Router::module_name( $zone, $post_type )
		);
	}

	/**
	 * Returns true when Zone query-rewrite is active for the given post_type + zone.
	 *
	 * @param string $post_type Post type slug.
	 * @param string $zone      Zone identifier.
	 * @return bool
	 */
	public static function should_query_from_zone( string $post_type, string $zone ): bool {
		return TMDO_Feature_Flags::is_query_active(
			TMDO_Zone_Router::module_name( $zone, $post_type )
		);
	}

	/**
	 * Flush the request-level entity bridge cache.
	 * Call this in test setUp to isolate test cases.
	 */
	public static function flush_cache(): void {
		self::$entity_bridge_cache = array();
	}
}